libnm, docs: docs fixes

Update the docs build to include and exclude the correct files.

Fill in some missing documentation, and fix problems in the existing
docs. (In particular, "<" can't appear as a literal in documentation,
so change it to "&lt;". Also, "PKCS#12" has to be written as
"PKCS#<!-- -->12", or gtk-doc will think "#12" is a reference to a
type named "12".)

4 files changed, 49 insertions, 32 deletions

diff --git a/libnm/nm-device.c b/libnm/nm-device.c
index 29f5db8d33..ba5dbacb85 100644
--- a/libnm/nm-device.c
+++ b/libnm/nm-device.c
@@ -1568,8 +1568,7 @@ get_short_vendor (NMDevice *device)
  * nm_device_get_description:
  * @device: an #NMDevice
  *
- * Gets a description of @device, incorporating the results of
- * nm_device_get_short_vendor() and nm_device_get_short_product().
+ * Gets a description of @device, based on its vendor and product names.
  *
  * Returns: a description of @device. If either the vendor or the
  *   product name is unknown, this returns the interface name.
diff --git a/libnm/nm-types.h b/libnm/nm-types.h
index 2e62ffdea3..3602878a6a 100644
--- a/libnm/nm-types.h
+++ b/libnm/nm-types.h
@@ -49,8 +49,6 @@ typedef struct _NMObject            NMObject;
 typedef struct _NMRemoteConnection  NMRemoteConnection;
 typedef struct _NMSecretAgent       NMSecretAgent;
 typedef struct _NMVpnConnection     NMVpnConnection;
-typedef struct _NMVpnEditorPlugin   NMVpnEditorPlugin;
-typedef struct _NMVpnEditor         NMVpnEditor;
 typedef struct _NMWimaxNsp          NMWimaxNsp;
 
 #endif  /* NM_TYPES_H */
diff --git a/libnm/nm-vpn-editor-plugin.h b/libnm/nm-vpn-editor-plugin.h
index 76b365876e..5910aa3653 100644
--- a/libnm/nm-vpn-editor-plugin.h
+++ b/libnm/nm-vpn-editor-plugin.h
@@ -32,6 +32,9 @@
 
 G_BEGIN_DECLS
 
+typedef struct _NMVpnEditorPlugin NMVpnEditorPlugin;
+typedef struct _NMVpnEditor NMVpnEditor;
+
 /* Plugin's factory function that returns a GObject that implements
  * NMVpnEditorPlugin.
  */
@@ -75,41 +78,44 @@ typedef enum /*< flags >*/ {
 /* D-Bus service name of the plugin's VPN service */
 #define NM_VPN_EDITOR_PLUGIN_SERVICE "service"
 
+/**
+ * NMVpnEditorPluginInterface:
+ * @g_iface: the parent interface
+ * @get_editor: returns an #NMVpnEditor, pre-filled with values from @connection
+ *   if non-%NULL.
+ * @get_capabilities: returns a bitmask of capabilities.
+ * @import_from_file: Try to import a connection from the specified path.  On
+ *   success, return a partial #NMConnection object.  On error, return %NULL and
+ *   set @error with additional information.  Note that @error can be %NULL, in
+ *   which case no additional error information should be provided.
+ * @export_to_file: Export the given connection to the specified path.  Return
+ *   %TRUE on success.  On error, return %FALSE and set @error with additional
+ *   error information.  Note that @error can be %NULL, in which case no
+ *   additional error information should be provided.
+ * @get_suggested_filename: For a given connection, return a suggested file
+ *   name.  Returned value will be %NULL or a suggested file name to be freed by
+ *   the caller.
+ *
+ * Interface for VPN editor plugins.
+ */
 typedef struct {
 	GTypeInterface g_iface;
 
-	/* Returns an #NMVpnEditor, pre-filled with values from @connection if
-	 * non-%NULL.
-	 */
 	NMVpnEditor * (*get_editor) (NMVpnEditorPlugin *plugin,
 	                             NMConnection *connection,
 	                             GError **error);
 
-	/* Plugin's capabiltity function that returns a bitmask of capabilities. */
 	NMVpnEditorPluginCapability (*get_capabilities) (NMVpnEditorPlugin *plugin);
 
-	/* Try to import a connection from the specified path.  On success, return a
-	 * partial #NMConnection object.  On error, return %NULL and set @error with
-	 * additional information.  Note that @error can be %NULL, in which case no
-	 * additional error information should be provided.
-	 */
 	NMConnection * (*import_from_file) (NMVpnEditorPlugin *plugin,
 	                                    const char *path,
 	                                    GError **error);
 
-	/* Export the given connection to the specified path.  Return %TRUE on success.
-	 * On error, return %FALSE and set @error with additional error information.
-	 * Note that @error can be %NULL, in which case no additional error information
-	 * should be provided.
-	 */
 	gboolean (*export_to_file) (NMVpnEditorPlugin *plugin,
 	                            const char *path,
 	                            NMConnection *connection,
 	                            GError **error);
 
-	/* For a given connection, return a suggested file name.  Returned value
-	 * will be %NULL or a suggested file name to be freed by the caller.
-	 */
 	char * (*get_suggested_filename) (NMVpnEditorPlugin *plugin, NMConnection *connection);
 } NMVpnEditorPluginInterface;
 
@@ -140,28 +146,33 @@ char         *nm_vpn_editor_plugin_get_suggested_filename (NMVpnEditorPlugin *pl
 #define NM_IS_VPN_EDITOR(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_VPN_EDITOR))
 #define NM_VPN_EDITOR_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), NM_TYPE_VPN_EDITOR, NMVpnEditorInterface))
 
+/**
+ * NMVpnEditorInterface:
+ * @g_iface: the parent interface
+ * @get_widget: return the #GtkWidget for the VPN editor's UI
+ * @placeholder: not currently used
+ * @update_connection: called to save the user-entered options to the connection
+ *   object.  Should return %FALSE and set @error if the current options are
+ *   invalid.  @error should contain enough information for the plugin to
+ *   determine which UI widget is invalid at a later point in time.  For
+ *   example, creating unique error codes for what error occurred and populating
+ *   the message field of @error with the name of the invalid property.
+ * @changed: emitted when the value of a UI widget changes.  May trigger a
+ *   validity check via @update_connection to write values to the connection.
+ *
+ * Interface for editing a specific #NMConnection
+ */
 typedef struct {
 	GTypeInterface g_iface;
 
-	/* Return the #GtkWidget for the VPN editor's UI */
 	GObject * (*get_widget) (NMVpnEditor *editor);
 
 	void (*placeholder) (void);
 
-	/* Called to save the user-entered options to the connection object.  Should
-	 * return %FALSE and set @error if the current options are invalid.  @error
-	 * should contain enough information for the plugin to determine which UI
-	 * widget is invalid at a later point in time.  For example, creating unique
-	 * error codes for what error occurred and populating the message field
-	 * of @error with the name of the invalid property.
-	 */
 	gboolean (*update_connection) (NMVpnEditor *editor,
 	                               NMConnection *connection,
 	                               GError **error);
 
-	/* Emitted when the value of a UI widget changes.  May trigger a validity
-	 * check via update_connection() to write values to the connection.
-	 */
 	void (*changed) (NMVpnEditor *editor);
 } NMVpnEditorInterface;
 
diff --git a/libnm/nm-wimax-nsp.h b/libnm/nm-wimax-nsp.h
index a8f9105268..cdc7b23665 100644
--- a/libnm/nm-wimax-nsp.h
+++ b/libnm/nm-wimax-nsp.h
@@ -41,6 +41,15 @@ G_BEGIN_DECLS
 #define NM_WIMAX_NSP_SIGNAL_QUALITY "signal-quality"
 #define NM_WIMAX_NSP_NETWORK_TYPE   "network-type"
 
+/**
+ * NMWimaxNspNetworkType:
+ * @NM_WIMAX_NSP_NETWORK_TYPE_UNKNOWN: unknown network type
+ * @NM_WIMAX_NSP_NETWORK_TYPE_HOME: home network
+ * @NM_WIMAX_NSP_NETWORK_TYPE_PARTNER: partner network
+ * @NM_WIMAX_NSP_NETWORK_TYPE_ROAMING_PARTNER: roaming partner network
+ *
+ * WiMAX network type.
+ */
 typedef enum {
 	NM_WIMAX_NSP_NETWORK_TYPE_UNKNOWN         = 0,
 	NM_WIMAX_NSP_NETWORK_TYPE_HOME            = 1,