Class description now contains doc from "SECTION:foo" instead of the typedef (since 1.66.0)
Since commit de6512b3 the gir file for NetworkManager is parsed differently.
For example, we have documentation for the class and for the file:
With commit de6512b3 the generated gir file is different:
@@ -38329,22 +38378,25 @@ two connections.</doc> </member> </enumeration> <class name="SettingConnection" c:symbol-prefix="setting_connection" c:type="NMSettingConnection" parent="Setting" glib:type-name="NMSettingConnection" glib:get-type="nm_setting_connection_get_type" glib:type-struct="SettingConnectionClass"> <doc xml:space="preserve" - filename="libnm-core/nm-setting-connection.h" - line="130">General Connection Profile Settings</doc> + filename="libnm-core/nm-setting-connection.c" + line="22">The #NMSettingConnection object is a #NMSetting subclass that describes +properties that apply to all #NMConnection objects, regardless of what type +of network connection they describe. Each #NMConnection object must contain +a #NMSettingConnection setting.</doc> <source-position filename="libnm-core/nm-setting-connection.h" line="144"/> <constructor name="new" c:identifier="nm_setting_connection_new"> <doc xml:space="preserve" filename="libnm-core/nm-setting-connection.c" line="1743">Creates a new #NMSettingConnection object with default values.</doc> <source-position filename="libnm-core/nm-setting-connection.h" line="148"/> <return-value transfer-ownership="full"> <doc xml:space="preserve"
Note that we then take
NM-1.0.gir and generate the manual pages from it. For example,
man nm-settings-nmcli would previously read:
connection setting General Connection Profile Settings.
Now it reads:
connection setting The NMSettingConnection object is a NMSetting subclass that describes properties that apply to all NMConnection objects, regardless of what type of network connection they describe. Each NMConnection object must contain a "connection" setting..
See also the generated gtk-doc of this class: https://networkmanager.pages.freedesktop.org/NetworkManager/libnm/NMSettingConnection.html . There
"SECTION:nm-setting-connection" is used as general description of the entire page, while there is still a dedicated description of the
typedef struct _NMSettingConnection NMSettingConnection;.
For one, it's a bit cumbersome that the way that worked for years now broke, but OK, if this is the progress. However, I wonder whether change de6512b3 is correct. Why do we now prefer the
"SECTION:nm-setting-connection" description over the description for
NMSettingConnection: -- in
NM-1.0.gir where we really should show the description of the class.
How to reproduce: build NetworkManager
git clone https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git cd NetworkManager git checkout -b test 1c3f7d823e17dbfc26ab11ef8943135b2c6961c5 # optionally install build dependencies sudo ./contrib/fedora/REQUIRED_PACKAGES ./autogen.sh --enable-gtk-doc make -j 8 libnm/NM-1.0.gir make -j 8 man/nm-settings-nmcli.5