Skip to content

man nm-settings-nmcli: autogenerate info about valid input format and values

Íñigo Huguet requested to merge ih/man-nmcli-fmt into main

Summary

Until now, it was only shown the C type as format, but this was in many cases inaccurate or not very informative. Using the information already available in nm-meta-setting-desc.c, which is the info used by nmcli to parse the user's input, we can get and show more info and more accurate.

Show a more accurate description of the properties' format. Example:

  • Before: Format: int32
  • After: Format: choice (NMSettingIP4LinkLocal)

Also, show what are the valid values if they are limited to a range or a list of values. Examples:

  • Valid values: default (0), auto (1), disabled (2), enabled (3)
  • Valid values: true/yes/on, false/no/off
  • Valid values: 10 - 20

Also, show whether there are special values with special meanings or alias. Example:

  • Special values: unset (-1), default (0)

Also, the expansion of constants from the gtkdoc comments has been improved to show more relevant info, affecting only to the generation of the nm-settings-* pages (and not to the documentation under doc/): constants of the type %ENUM_VALUE_NAME were expanded to texts like NM_TUNNEL_IP_MODE (1), but now they are expanded to a text more meaningful for the user, which differs depending on the man page that is being generated:

  • In nm-settings-nmcli: "ipip" (1), "disabled" (0x1)
  • In nm-settings-dbus: 1 (ipip), 0x1 (disabled)

Finally, a new expression #EnumName:* will be recognized in the "property-infos" comments (like ---nmcli--- comments). In the description field of the generated XMLs, they will be expanded to a list of all the possible values of EnumName. In the description-docbook field, they will be expanded to the list of all possible values, including the documentation of each one of them. In nm-settings-nmcli, the description-docbook field is used by default. Example, expansion of Valid values: #NMIPTunnelMode:* in a ---nmcli--- comment:

Valid values:
       •   ipip (1) - IP in IP tunnel
       •   gre (2) - GRE tunnel
       •   sit (3) - SIT tunnel
       •   isatap (4) - ISATAP tunnel
       •   vti (5) - VTI tunnel
       •   ip6ip6 (6) - IPv6 in IPv6 tunnel
       •   ipip6 (7) - IPv4 in IPv6 tunnel
       •   ip6gre (8) - IPv6 GRE tunnel
       •   vti6 (9) - IPv6 VTI tunnel
       •   gretap (10) - GRETAP tunnel
       •   ip6gretap (11) - IPv6 GRETAP tunnel

Purpose

Autogenerating the accepted format and values will show valuable and accurate information for the users. For the developers, it will be easier to document and more difficult to forget updating documentation, because it won't be necessary to do it as many times.

Properly formatted expansion of %ENUM_VALUE_NAME from gtkdoc will help to show more meaningful information to the users, showing names that they can directly enter as property value, instead of a C identifier that they can't use.

The expansion of #EnumName:* expressions in the "property-infos" comments will help to maintain more up to date documentation of those properties that need better documentation of what each value mean.

Checklist

Please read https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/main/CONTRIBUTING.md before opening the merge request. In particular, check that:

  • the subject for all commits is concise and explicative
  • the message for all commits explains the reason for the change
  • the source is properly formatted
  • any relevant documentation is up to date
  • you have added unit tests if applicable

Merge request reports