mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git
synced 2026-05-18 01:08:08 +02:00
8460040df1
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. |
||
|---|---|---|
| .. | ||
| nm-in-container | ||
| check-compare-generated.sh | ||
| check-config-options.sh | ||
| check-docs.sh | ||
| check-exports.sh | ||
| check-gitlab-ci.sh | ||
| check-nm-autoptr.sh | ||
| check-tree.sh | ||
| check-vapi.sh | ||
| create-exports-NetworkManager.sh | ||
| debug-helper.py | ||
| enums-to-docbook.pl | ||
| generate-docs-nm-property-infos.py | ||
| generate-docs-nm-settings-docs-gir.py | ||
| generate-docs-nm-settings-docs-merge.py | ||
| generate-docs-settings-docs.py | ||
| meson-post-install.sh | ||
| run-nm-test.sh | ||
| test-build.sh | ||
| test-cloud-meta-mock.py | ||
| test-networkmanager-service.py | ||
| test-sudo-wrapper.sh | ||