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:
Excerpt of NM-1.0.gir
:
@@ -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