Re: libnm-util reference manual

[Dan Williams <dcbw redhat com>]

On Sat, 2012-09-22 at 15:25 -0400, Gene Czarcinski wrote:
> I am in the process of developing some patches to NetworkManager which 
> implementingdhcp dynamic dns updating for dhcp6.  The patches involve 
> some small updating to the code in libnm-util.  There is a reference 
> manual for libnm-util.  What is the process/procedure for doing the 
> updates to that?

The reference manual is actually autogenerated from code comments.
There are a lot of docbook-style comments in the code, like:

/**
 * nm_foo_bar()
 * @arg1: xxxx
 * @arg2: xxx
 *
 * This is a description of the function.
 *
 * Returns: description of the return value
 */

For the object properties, if you added any, the documentation is
generated from the property descriptions right above the
g_object_class_add_property() call.  The 'settings specification' is
generated from the text *in* the g_object_class_add_property() call
(instead of the docbook comments) and thus the text inside that call
should be substantially the same as the docbook for that property.  Like
so:

/**
 * NMSettingWired:mtu:
 *
 * If non-zero, only transmit packets of the specified size or smaller,
 * breaking larger packets up into multiple Ethernet frames.
 **/
g_object_class_install_property
	(object_class, PROP_MTU,
	 g_param_spec_uint (NM_SETTING_WIRED_MTU,
			"MTU",
			"If non-zero, only transmit packets of the specified "
			"size or smaller, breaking larger packets up into "
			"multiple Ethernet frames.",
			0, G_MAXUINT32, 0,
			<blah blah flags blah blah>));

Dan