settings: clarify ownership of objects returned from plugin's add_connection() hook

Plugin owns the object and callers must reference it if they wish to use it outside
of the function they called "add" from.  Likewise, callers of the ConnectionProvider's
add_connection method must also reference the returned object if they wish to
continue using it.

3 files changed, 32 insertions, 1 deletions

diff --git a/src/nm-connection-provider.c b/src/nm-connection-provider.c
index 467d99d2b1..4a7019441b 100644
--- a/src/nm-connection-provider.c
+++ b/src/nm-connection-provider.c
@@ -49,6 +49,20 @@ nm_connection_provider_has_connections_loaded (NMConnectionProvider *self)
 	return NM_CONNECTION_PROVIDER_GET_INTERFACE (self)->has_connections_loaded (self);
 }
 
+/**
+ * nm_connection_provider_add_connection:
+ * @self: the #NMConnectionProvider
+ * @connection: the source connection to create a new #NMSettingsConnection from
+ * @save_to_disk: %TRUE to save the connection to disk immediately, %FALSE to
+ * not save to disk
+ * @error: on return, a location to store any errors that may occur
+ *
+ * Creates a new #NMSettingsConnection for the given source @connection.  
+ * The plugin owns the returned object and the caller must reference the object
+ * to continue using it.
+ *
+ * Returns: the new #NMSettingsConnection or %NULL
+ */
 NMConnection *
 nm_connection_provider_add_connection (NMConnectionProvider *self,
                                        NMConnection *connection,
diff --git a/src/settings/nm-system-config-interface.c b/src/settings/nm-system-config-interface.c
index 0d9426da32..65c85b0520 100644
--- a/src/settings/nm-system-config-interface.c
+++ b/src/settings/nm-system-config-interface.c
@@ -156,6 +156,22 @@ nm_system_config_interface_get_unmanaged_specs (NMSystemConfigInterface *config)
 	return NULL;
 }
 
+/**
+ * nm_system_config_interface_add_connection:
+ * @config: the #NMSystemConfigInterface
+ * @connection: the source connection to create a plugin-specific
+ * #NMSettingsConnection from
+ * @save_to_disk: %TRUE to save the connection to disk immediately, %FALSE to
+ * not save to disk
+ * @error: on return, a location to store any errors that may occur
+ *
+ * Creates a new #NMSettingsConnection for the given source @connection.  If the
+ * plugin cannot handle the given connection type, it should return %NULL and
+ * set @error.  The plugin owns the returned object and the caller must reference
+ * the object if it wishes to continue using it.
+ *
+ * Returns: the new #NMSettingsConnection or %NULL
+ */
 NMSettingsConnection *
 nm_system_config_interface_add_connection (NMSystemConfigInterface *config,
                                            NMConnection *connection,
diff --git a/src/settings/nm-system-config-interface.h b/src/settings/nm-system-config-interface.h
index cd65a6a5db..ad40f9cf0c 100644
--- a/src/settings/nm-system-config-interface.h
+++ b/src/settings/nm-system-config-interface.h
@@ -118,7 +118,8 @@ struct _NMSystemConfigInterface {
 	 * Initialize the plugin-specific connection and return a new
 	 * NMSettingsConnection subclass that contains the same settings as the
 	 * original connection.  The connection should only be saved to backing
-	 * storage if @save_to_disk is TRUE.
+	 * storage if @save_to_disk is TRUE.  The returned object is owned by the
+	 * plugin and must be referenced by the owner if necessary.
 	 */
 	NMSettingsConnection * (*add_connection) (NMSystemConfigInterface *config,
 	                                          NMConnection *connection,