Skip to content

[RFC] docs: add a new "expand enumval" type of tag to autopopulate all the possible enum values in documentation

Íñigo Huguet requested to merge ih/tunnel_doc into main

DO NOT MERGE! This is an RFC to get some feedback and see if anything could be done better in a different way.

Having to type manually all the accepted values in each property's documentation is very error prone: you can make typos and you will probably forget to always update them when new possible values are added.

If the possible values are the variant of an enum, we can use the introspection data to get all the possible values for that enum and their descriptions. With that info, we can automatically generate the documentation with an always up to date list of accepted values.

Also, for nmcli documentation we want to show the pretty nickname of each value because it's the more user friendly way for users to enter the data. C names like NM_IP_TUNNEL_MODE_IPIP have no value here so they mustn't be shown, and the pretty nickname "ipip" must be shown instead.

With this commit, the special string #EnumName:* can be used in docs and it will be expanded to the complete list of accepted values. If the docs that are being generated are for nmcli, pretty nicknames will be used instead of C names.

It is also desirable to show a description of what each value means in nmcli man pages. To do this, the special string #EnumName:** can be used. It will expand the same way than #EnumName:* in the "description" field of the property, but it will expand to a formatted list with all the values and their explanations in the "description-docbook" field. The "description-docbook" field is currently only used for the nm-settings-nmcli man page.

To expand a single enum value in the proper format (i.e. using nicknames in nmcli docs), use the string "%ENUM_VALUE".

However, this feature has an important limitation: it can only be used for man/nm-settings-*.5 files generation, and the expansion only happens in the special tagged comments (like ---nmcli---), not in the normal gtkdoc comments. There are 2 reasons:

  1. Any other documentation, other than man/nm-settings-*.5, is generated directly with gtkdoc, that doesn't support this expansion feature.
  2. The gtkdoc comment applies to everything, either nmcli or dbus, keyfile, etc. We can't format the expanded text in a proper way without knowing where it's going to be used.

Some enum values that are not intended to be public can be marked as NM.internal to be skipped from documentation.

Finally, commit 044b6a1d use the new features to properly document all the accepted values of ip-tunnel.mode property. The man page's result texts for this property are:


ipip (1), gre (2), sit (3), isatap (4), vti (5), ip6ip6 (6), ipip6 (7), ip6gre (8), vti6 (9), gretap (10), ip6gretap (11)



In that commit, if using #IPTunnelMode:** instead of a single *, the result text for nm-settings-nmcli would be:

        The tunneling mode, 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
Edited by Íñigo Huguet

Merge request reports