docs: Reorganize and fix

This commit completes the sections file with subsections, moves most
documentation to headers (no real reason to, especially given that
changes there may cause unwanted rebuilds, but it feels better to have
it in the headers) and fixes some annotations.

Closes https://gitlab.gnome.org/GNOME/nautilus/issues/565

20 files changed, 344 insertions, 312 deletions

diff --git a/libnautilus-extension/nautilus-column-provider.c b/libnautilus-extension/nautilus-column-provider.c
index f40bebaac..a66ef85b1 100644
--- a/libnautilus-extension/nautilus-column-provider.c
+++ b/libnautilus-extension/nautilus-column-provider.c
@@ -25,26 +25,11 @@
 
 G_DEFINE_INTERFACE (NautilusColumnProvider, nautilus_column_provider, G_TYPE_OBJECT)
 
-/**
- * SECTION:nautilus-column-provider
- * @title: NautilusColumnProvider
- * @short_description: Interface to provide additional list view columns
- *
- * #NautilusColumnProvider allows extension to provide additional columns
- * in the file manager list view.
- */
-
 static void
 nautilus_column_provider_default_init (NautilusColumnProviderInterface *klass)
 {
 }
 
-/**
- * nautilus_column_provider_get_columns:
- * @provider: a #NautilusColumnProvider
- *
- * Returns: (element-type NautilusColumn) (transfer full): the provided #NautilusColumn objects
- */
 GList *
 nautilus_column_provider_get_columns (NautilusColumnProvider *self)
 {
diff --git a/libnautilus-extension/nautilus-column-provider.h b/libnautilus-extension/nautilus-column-provider.h
index e3b44565f..e9d820b6b 100644
--- a/libnautilus-extension/nautilus-column-provider.h
+++ b/libnautilus-extension/nautilus-column-provider.h
@@ -50,10 +50,19 @@ G_DECLARE_INTERFACE (NautilusColumnProvider, nautilus_column_provider,
 typedef NautilusColumnProviderInterface NautilusColumnProviderIface;
 
 /**
+ * SECTION:nautilus-column-provider
+ * @title: NautilusColumnProvider
+ * @short_description: Interface to provide additional list view columns
+ *
+ * #NautilusColumnProvider allows extension to provide additional columns
+ * in the file manager list view.
+ */
+
+/**
  * NautilusColumnProviderInterface:
  * @g_iface: The parent interface.
  * @get_columns: Returns a #GList of #NautilusColumn.
- *   See nautilus_column_provider_get_columns() for details.
+ *               See nautilus_column_provider_get_columns() for details.
  *
  * Interface for extensions to provide additional list view columns.
  */
@@ -64,7 +73,12 @@ struct _NautilusColumnProviderInterface
     GList *(*get_columns) (NautilusColumnProvider *provider);
 };
 
-/* Interface Functions */
+/**
+ * nautilus_column_provider_get_columns:
+ * @provider: a #NautilusColumnProvider
+ *
+ * Returns: (element-type NautilusColumn) (transfer full): the provided #NautilusColumn objects
+ */
 GList *nautilus_column_provider_get_columns (NautilusColumnProvider *provider);
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS
diff --git a/libnautilus-extension/nautilus-column.c b/libnautilus-extension/nautilus-column.c
index a36885091..38a78141e 100644
--- a/libnautilus-extension/nautilus-column.c
+++ b/libnautilus-extension/nautilus-column.c
@@ -51,29 +51,6 @@ struct _NautilusColumn
 
 G_DEFINE_TYPE (NautilusColumn, nautilus_column, G_TYPE_OBJECT);
 
-/**
- * SECTION:nautilus-column
- * @title: NautilusColumn
- * @short_description: List view column descriptor object
- *
- * #NautilusColumn is an object that describes a column in the file manager
- * list view. Extensions can provide #NautilusColumn by registering a
- * #NautilusColumnProvider and returning them from
- * nautilus_column_provider_get_columns(), which will be called by the main
- * application when creating a view.
- */
-
-/**
- * nautilus_column_new:
- * @name: identifier of the column
- * @attribute: the file attribute to be displayed in the column
- * @label: the user-visible label for the column
- * @description: a user-visible description of the column
- *
- * Creates a new column
- *
- * Returns: a newly created #NautilusColumn
- */
 NautilusColumn *
 nautilus_column_new (const char *name,
                      const char *attribute,
diff --git a/libnautilus-extension/nautilus-column.h b/libnautilus-extension/nautilus-column.h
index 11fb81e9d..bf07779c6 100644
--- a/libnautilus-extension/nautilus-column.h
+++ b/libnautilus-extension/nautilus-column.h
@@ -37,6 +37,27 @@ G_BEGIN_DECLS
 
 G_DECLARE_FINAL_TYPE (NautilusColumn, nautilus_column, NAUTILUS, COLUMN, GObject)
 
+/**
+ * SECTION:nautilus-column
+ * @title: NautilusColumn
+ * @short_description: List view column descriptor object
+ *
+ * #NautilusColumn is an object that describes a column in the file manager
+ * list view. Extensions can provide #NautilusColumn by registering a
+ * #NautilusColumnProvider and returning them from
+ * nautilus_column_provider_get_columns(), which will be called by the main
+ * application when creating a view.
+ */
+
+/**
+ * nautilus_column_new:
+ * @name: (not nullable): identifier of the column
+ * @attribute: (not nullable): the file attribute to be displayed in the column
+ * @label: (not nullable): the user-visible label for the column
+ * @description: (not nullable): a user-visible description of the column
+ *
+ * Returns: (transfer full): a new #NautilusColumn
+ */
 NautilusColumn *nautilus_column_new  (const char *name,
                                       const char *attribute,
                                       const char *label,
diff --git a/libnautilus-extension/nautilus-extension.h b/libnautilus-extension/nautilus-extension.h
index 7723f453a..1c3ca5a9b 100644
--- a/libnautilus-extension/nautilus-extension.h
+++ b/libnautilus-extension/nautilus-extension.h
@@ -34,9 +34,29 @@
  * @title: Extension entry points
  */
 
+/**
+ * nautilus_module_initialize:
+ * @module: a #GTypeModule used in type registration
+ *
+ * Called when the extension is begin loaded to register the types it exports
+ * and to perform other initializations.
+ */
 void nautilus_module_initialize (GTypeModule  *module);
+/**
+ * nautilus_module_shutdown:
+ *
+ * Called when the extension is being unloaded.
+ */
 void nautilus_module_shutdown   (void);
+/**
+ * nautilus_module_list_types:
+ * @types: (out) (array length=num_types): array of GType *
+ * @num_types: the number of types in the array
+ *
+ * Called after the extension has been initialized and has registered all the
+ * types it exports, to load them into Nautilus.
+ */
 void nautilus_module_list_types (const GType **types,
                                  int          *num_types);
 
-#endif
\ No newline at end of file
+#endif
diff --git a/libnautilus-extension/nautilus-file-info.c b/libnautilus-extension/nautilus-file-info.c
index 2a4c9d478..484e6c1c0 100644
--- a/libnautilus-extension/nautilus-file-info.c
+++ b/libnautilus-extension/nautilus-file-info.c
@@ -26,22 +26,6 @@ G_DEFINE_INTERFACE (NautilusFileInfo, nautilus_file_info, G_TYPE_OBJECT)
 
 NautilusFileInfo * (*nautilus_file_info_getter)(GFile * location, gboolean create);
 
-/**
- * SECTION:nautilus-file-info
- * @title: NautilusFileInfo
- * @short_description: File interface for nautilus extensions
- *
- * #NautilusFileInfo provides methods to get and modify information
- * about file objects in the file manager.
- */
-
-/**
- * nautilus_file_info_list_copy:
- * @files: (element-type NautilusFileInfo): the files to copy
- *
- * Returns: (element-type NautilusFileInfo) (transfer full): a copy of @files.
- *  Use #nautilus_file_info_list_free to free the list and unref its contents.
- */
 GList *
 nautilus_file_info_list_copy (GList *files)
 {
@@ -57,12 +41,6 @@ nautilus_file_info_list_copy (GList *files)
     return ret;
 }
 
-/**
- * nautilus_file_info_list_free:
- * @files: (element-type NautilusFileInfo): a list created with
- *   #nautilus_file_info_list_copy
- *
- */
 void
 nautilus_file_info_list_free (GList *files)
 {
@@ -123,12 +101,6 @@ nautilus_file_info_get_name (NautilusFileInfo *self)
     return iface->get_name (self);
 }
 
-/**
- * nautilus_file_info_get_location:
- * @file_info: a #NautilusFileInfo
- *
- * Returns: (transfer full): a #GFile for the location of @file_info
- */
 GFile *
 nautilus_file_info_get_location (NautilusFileInfo *self)
 {
@@ -170,13 +142,6 @@ nautilus_file_info_get_activation_uri (NautilusFileInfo *self)
     return iface->get_activation_uri (self);
 }
 
-/**
- * nautilus_file_info_get_parent_location:
- * @file_info: a #NautilusFileInfo
- *
- * Returns: (allow-none) (transfer full): a #GFile for the parent location of @file_info,
- *   or %NULL if @file_info has no parent
- */
 GFile *
 nautilus_file_info_get_parent_location (NautilusFileInfo *self)
 {
@@ -205,13 +170,6 @@ nautilus_file_info_get_parent_uri (NautilusFileInfo *self)
     return iface->get_parent_uri (self);
 }
 
-/**
- * nautilus_file_info_get_parent_info:
- * @file_info: a #NautilusFileInfo
- *
- * Returns: (allow-none) (transfer full): a #NautilusFileInfo for the parent of @file_info,
- *   or %NULL if @file_info has no parent
- */
 NautilusFileInfo *
 nautilus_file_info_get_parent_info (NautilusFileInfo *self)
 {
@@ -226,13 +184,6 @@ nautilus_file_info_get_parent_info (NautilusFileInfo *self)
     return iface->get_parent_info (self);
 }
 
-/**
- * nautilus_file_info_get_mount:
- * @file_info: a #NautilusFileInfo
- *
- * Returns: (allow-none) (transfer full): a #GMount for the mount of @file_info,
- *   or %NULL if @file_info has no mount
- */
 GMount *
 nautilus_file_info_get_mount (NautilusFileInfo *self)
 {
@@ -382,12 +333,6 @@ nautilus_file_info_invalidate_extension_info (NautilusFileInfo *self)
     iface->invalidate_extension_info (self);
 }
 
-/**
- * nautilus_file_info_lookup:
- * @location: the location to lookup the file info for
- *
- * Returns: (transfer full): a #NautilusFileInfo
- */
 NautilusFileInfo *
 nautilus_file_info_lookup (GFile *location)
 {
@@ -396,12 +341,6 @@ nautilus_file_info_lookup (GFile *location)
     return nautilus_file_info_getter (location, FALSE);
 }
 
-/**
- * nautilus_file_info_create:
- * @location: the location to create the file info for
- *
- * Returns: (transfer full): a #NautilusFileInfo
- */
 NautilusFileInfo *
 nautilus_file_info_create (GFile *location)
 {
@@ -410,12 +349,6 @@ nautilus_file_info_create (GFile *location)
     return nautilus_file_info_getter (location, TRUE);
 }
 
-/**
- * nautilus_file_info_lookup_for_uri:
- * @uri: the URI to lookup the file info for
- *
- * Returns: (transfer full): a #NautilusFileInfo
- */
 NautilusFileInfo *
 nautilus_file_info_lookup_for_uri (const char *uri)
 {
@@ -428,12 +361,6 @@ nautilus_file_info_lookup_for_uri (const char *uri)
     return nautilus_file_info_lookup (location);
 }
 
-/**
- * nautilus_file_info_create_for_uri:
- * @uri: the URI to lookup the file info for
- *
- * Returns: (transfer full): a #NautilusFileInfo
- */
 NautilusFileInfo *
 nautilus_file_info_create_for_uri (const char *uri)
 {
diff --git a/libnautilus-extension/nautilus-file-info.h b/libnautilus-extension/nautilus-file-info.h
index a7da8ec6b..dbd91e529 100644
--- a/libnautilus-extension/nautilus-file-info.h
+++ b/libnautilus-extension/nautilus-file-info.h
@@ -46,46 +46,55 @@ G_DECLARE_INTERFACE (NautilusFileInfo, nautilus_file_info, NAUTILUS, FILE_INFO,
 typedef struct NautilusFile NautilusFile;
 
 /**
+ * SECTION:nautilus-file-info
+ * @title: NautilusFileInfo
+ * @short_description: File interface for nautilus extensions
+ *
+ * #NautilusFileInfo provides methods to get and modify information
+ * about file objects in the file manager.
+ */
+
+/**
  * NautilusFileInfoInterface:
  * @g_iface: The parent interface.
  * @is_gone: Returns whether the file info is gone.
- *   See nautilus_file_info_is_gone() for details.
+ *           See nautilus_file_info_is_gone() for details.
  * @get_name: Returns the file name as a string.
- *   See nautilus_file_info_get_name() for details.
+ *            See nautilus_file_info_get_name() for details.
  * @get_uri: Returns the file URI as a string.
- *   See nautilus_file_info_get_uri() for details.
+ *           See nautilus_file_info_get_uri() for details.
  * @get_parent_uri: Returns the file parent URI as a string.
- *   See nautilus_file_info_get_parent_uri() for details.
+ *                  See nautilus_file_info_get_parent_uri() for details.
  * @get_uri_scheme: Returns the file URI scheme as a string.
- *   See nautilus_file_info_get_uri_scheme() for details.
+ *                  See nautilus_file_info_get_uri_scheme() for details.
  * @get_mime_type: Returns the file mime type as a string.
- *   See nautilus_file_info_get_mime_type() for details.
+ *                 See nautilus_file_info_get_mime_type() for details.
  * @is_mime_type: Returns whether the file is the given mime type.
- *   See nautilus_file_info_is_mime_type() for details.
+ *                See nautilus_file_info_is_mime_type() for details.
  * @is_directory: Returns whether the file is a directory.
- *   See nautilus_file_info_is_directory() for details.
+ *                See nautilus_file_info_is_directory() for details.
  * @add_emblem: Adds an emblem to this file.
- *   See nautilus_file_info_add_emblem() for details.
+ *              See nautilus_file_info_add_emblem() for details.
  * @get_string_attribute: Returns the specified file attribute as a string.
- *   See nautilus_file_info_get_string_attribute() for details.
+ *                        See nautilus_file_info_get_string_attribute() for details.
  * @add_string_attribute: Sets the specified string file attribute value.
- *   See nautilus_file_info_add_string_attribute() for details.
+ *                        See nautilus_file_info_add_string_attribute() for details.
  * @invalidate_extension_info: Invalidates information of the file provided by extensions.
- *   See nautilus_file_info_invalidate_extension_info() for details.
+ *                             See nautilus_file_info_invalidate_extension_info() for details.
  * @get_activation_uri: Returns the file activation URI as a string.
- *   See nautilus_file_info_get_activation_uri() for details.
+ *                      See nautilus_file_info_get_activation_uri() for details.
  * @get_file_type: Returns the file type.
- *   See nautilus_file_info_get_file_type() for details.
+ *                 See nautilus_file_info_get_file_type() for details.
  * @get_location: Returns the file location as a #GFile.
- *   See nautilus_file_info_get_location() for details.
+ *                See nautilus_file_info_get_location() for details.
  * @get_parent_location: Returns the file parent location as a #GFile.
- *   See nautilus_file_info_get_parent_location() for details.
+ *                       See nautilus_file_info_get_parent_location() for details.
  * @get_parent_info: Returns the file parent #NautilusFileInfo.
- *   See nautilus_file_info_get_parent_info() for details.
+ *                   See nautilus_file_info_get_parent_info() for details.
  * @get_mount: Returns the file mount as a #GMount.
- *   See nautilus_file_info_get_mount() for details.
+ *             See nautilus_file_info_get_mount() for details.
  * @can_write: Returns whether the file is writable.
- *   See nautilus_file_info_can_write() for details.
+ *             See nautilus_file_info_can_write() for details.
  *
  * Interface for extensions to provide additional menu items.
  */
@@ -124,28 +133,77 @@ struct _NautilusFileInfoInterface
     gboolean          (*can_write)                 (NautilusFileInfo *file_info);
 };
 
+/**
+ * nautilus_file_info_list_copy:
+ * @files: (element-type NautilusFileInfo): the files to copy
+ *
+ * Returns: (element-type NautilusFileInfo) (transfer full): a copy of @files.
+ *  Use #nautilus_file_info_list_free to free the list and unref its contents.
+ */
 GList            *nautilus_file_info_list_copy            (GList            *files);
+/**
+ * nautilus_file_info_list_free:
+ * @files: (element-type NautilusFileInfo): a list created with #nautilus_file_info_list_copy
+ *
+ */
 void              nautilus_file_info_list_free            (GList            *files);
 
-/* Return true if the file has been deleted */
+/**
+ * nautilus_file_info_is_gone:
+ * @file_info: a #NautilusFileInfo
+ *
+ * Returns: whether the file has been deleted
+ */
 gboolean          nautilus_file_info_is_gone              (NautilusFileInfo *file_info);
 
 /* Name and Location */
 GFileType         nautilus_file_info_get_file_type        (NautilusFileInfo *file_info);
+/**
+ * nautilus_file_info_get_location:
+ * @file_info: a #NautilusFileInfo
+ *
+ * Returns: (transfer full): a #GFile for the location of @file_info
+ */
 GFile            *nautilus_file_info_get_location         (NautilusFileInfo *file_info);
 char             *nautilus_file_info_get_name             (NautilusFileInfo *file_info);
 char             *nautilus_file_info_get_uri              (NautilusFileInfo *file_info);
 char             *nautilus_file_info_get_activation_uri   (NautilusFileInfo *file_info);
+/**
+ * nautilus_file_info_get_parent_location:
+ * @file_info: a #NautilusFileInfo
+ *
+ * Returns: (allow-none) (transfer full): a #GFile for the parent location of @file_info,
+ *   or %NULL if @file_info has no parent
+ */
 GFile            *nautilus_file_info_get_parent_location  (NautilusFileInfo *file_info);
 char             *nautilus_file_info_get_parent_uri       (NautilusFileInfo *file_info);
+/**
+ * nautilus_file_info_get_mount:
+ * @file_info: a #NautilusFileInfo
+ *
+ * Returns: (nullable) (transfer full): a #GMount for the mount of @file_info,
+ *                                      or %NULL if @file_info has no mount
+ */
 GMount           *nautilus_file_info_get_mount            (NautilusFileInfo *file_info);
 char             *nautilus_file_info_get_uri_scheme       (NautilusFileInfo *file_info);
-/* It's not safe to call this recursively multiple times, as it works
+/**
+ * nautilus_file_info_get_parent_info:
+ * @file_info: a #NautilusFileInfo
+ *
+ * It's not safe to call this recursively multiple times, as it works
  * only for files already cached by Nautilus.
+ *
+ * Returns: (nullable) (transfer full): a #NautilusFileInfo for the parent of @file_info,
+ *                                      or %NULL if @file_info has no parent.
  */
 NautilusFileInfo *nautilus_file_info_get_parent_info      (NautilusFileInfo *file_info);
 
-/* File Type */
+/**
+ * nautilus_file_info_get_parent_info:
+ * @file_info: a #NautilusFileInfo
+ *
+ * Returns: (transfer full): the MIME type of @file_info
+ */
 char *            nautilus_file_info_get_mime_type        (NautilusFileInfo *file_info);
 gboolean          nautilus_file_info_is_mime_type         (NautilusFileInfo *file_info,
                                                            const char       *mime_type);
@@ -165,9 +223,33 @@ void              nautilus_file_info_add_string_attribute (NautilusFileInfo *fil
 /* Invalidating file info */
 void              nautilus_file_info_invalidate_extension_info (NautilusFileInfo *file_info);
 
+/**
+ * nautilus_file_info_lookup:
+ * @location: the location for which to look up a corresponding #NautilusFileInfo object
+ *
+ * Returns: (transfer full): a #NautilusFileInfo
+ */
 NautilusFileInfo *nautilus_file_info_lookup                (GFile *location);
+/**
+ * nautilus_file_info_create:
+ * @location: the location to create the file info for
+ *
+ * Returns: (transfer full): a #NautilusFileInfo
+ */
 NautilusFileInfo *nautilus_file_info_create                (GFile *location);
+/**
+ * nautilus_file_info_lookup_for_uri:
+ * @uri: the URI to lookup the file info for
+ *
+ * Returns: (transfer full): a #NautilusFileInfo
+ */
 NautilusFileInfo *nautilus_file_info_lookup_for_uri        (const char *uri);
+/**
+ * nautilus_file_info_create_for_uri:
+ * @uri: the URI to lookup the file info for
+ *
+ * Returns: (transfer full): a #NautilusFileInfo
+ */
 NautilusFileInfo *nautilus_file_info_create_for_uri        (const char *uri);
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS
diff --git a/libnautilus-extension/nautilus-info-provider.c b/libnautilus-extension/nautilus-info-provider.c
index 37e95b2b0..5fce65597 100644
--- a/libnautilus-extension/nautilus-info-provider.c
+++ b/libnautilus-extension/nautilus-info-provider.c
@@ -27,17 +27,6 @@
 
 G_DEFINE_INTERFACE (NautilusInfoProvider, nautilus_info_provider, G_TYPE_OBJECT)
 
-/**
- * SECTION:nautilus-info-provider
- * @title: NautilusInfoProvider
- * @short_description: Interface to provide additional information about files
- *
- * #NautilusInfoProvider allows extension to provide additional information about
- * files. When nautilus_info_provider_update_file_info() is called by the application,
- * extensions will know that it's time to add extra information to the provided
- * #NautilusFileInfo.
- */
-
 static void
 nautilus_info_provider_default_init (NautilusInfoProviderInterface *klass)
 {
diff --git a/libnautilus-extension/nautilus-info-provider.h b/libnautilus-extension/nautilus-info-provider.h
index 19f48f125..285f67253 100644
--- a/libnautilus-extension/nautilus-info-provider.h
+++ b/libnautilus-extension/nautilus-info-provider.h
@@ -49,6 +49,17 @@ G_DECLARE_INTERFACE (NautilusInfoProvider, nautilus_info_provider,
 typedef NautilusInfoProviderInterface NautilusInfoProviderIface;
 
 /**
+ * SECTION:nautilus-info-provider
+ * @title: NautilusInfoProvider
+ * @short_description: Interface to provide additional information about files
+ *
+ * #NautilusInfoProvider allows extension to provide additional information about
+ * files. When nautilus_info_provider_update_file_info() is called by the application,
+ * extensions will know that it's time to add extra information to the provided
+ * #NautilusFileInfo.
+ */
+
+/**
  * NautilusOperationHandle:
  *
  * Handle for asynchronous interfaces. These are opaque handles that must
@@ -89,9 +100,9 @@ typedef enum
  * NautilusInfoProviderInterface:
  * @g_iface: The parent interface.
  * @update_file_info: Returns a #NautilusOperationResult.
- *   See nautilus_info_provider_update_file_info() for details.
+ *                    See nautilus_info_provider_update_file_info() for details.
  * @cancel_update: Cancels a previous call to nautilus_info_provider_update_file_info().
- *   See nautilus_info_provider_cancel_update() for details.
+ *                 See nautilus_info_provider_cancel_update() for details.
  *
  * Interface for extensions to provide additional information about files.
  */
@@ -123,4 +134,4 @@ void                    nautilus_info_provider_update_complete_invoke (GClosure
                                                                        NautilusOperationHandle  *handle,
                                                                        NautilusOperationResult   result);
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS
diff --git a/libnautilus-extension/nautilus-location-widget-provider.c b/libnautilus-extension/nautilus-location-widget-provider.c
index 55f989741..5290d5183 100644
--- a/libnautilus-extension/nautilus-location-widget-provider.c
+++ b/libnautilus-extension/nautilus-location-widget-provider.c
@@ -26,28 +26,11 @@
 G_DEFINE_INTERFACE (NautilusLocationWidgetProvider, nautilus_location_widget_provider,
                     G_TYPE_OBJECT)
 
-/**
- * SECTION:nautilus-location-widget-provider
- * @title: NautilusLocationWidgetProvider
- * @short_description: Interface to provide additional location widgets
- *
- * #NautilusLocationWidgetProvider allows extension to provide additional location
- * widgets in the file manager views.
- */
-
 static void
 nautilus_location_widget_provider_default_init (NautilusLocationWidgetProviderInterface *klass)
 {
 }
 
-/**
- * nautilus_location_widget_provider_get_widget:
- * @provider: a #NautilusLocationWidgetProvider
- * @uri: the URI of the location
- * @window: parent #GtkWindow
- *
- * Returns: (transfer none): the location widget for @provider at @uri
- */
 GtkWidget *
 nautilus_location_widget_provider_get_widget (NautilusLocationWidgetProvider *self,
                                               const char                     *uri,
diff --git a/libnautilus-extension/nautilus-location-widget-provider.h b/libnautilus-extension/nautilus-location-widget-provider.h
index a6f656cce..f3573828f 100644
--- a/libnautilus-extension/nautilus-location-widget-provider.h
+++ b/libnautilus-extension/nautilus-location-widget-provider.h
@@ -51,6 +51,15 @@ G_DECLARE_INTERFACE (NautilusLocationWidgetProvider, nautilus_location_widget_pr
 typedef NautilusLocationWidgetProviderInterface NautilusLocationWidgetProviderIface;
 
 /**
+ * SECTION:nautilus-location-widget-provider
+ * @title: NautilusLocationWidgetProvider
+ * @short_description: Interface to provide additional location widgets
+ *
+ * #NautilusLocationWidgetProvider allows extension to provide additional location
+ * widgets in the file manager views.
+ */
+
+/**
  * NautilusLocationWidgetProviderInterface:
  * @g_iface: The parent interface.
  * @get_widget: Returns a #GtkWidget.
@@ -67,9 +76,16 @@ struct _NautilusLocationWidgetProviderInterface
                               GtkWidget                      *window);
 };
 
-/* Interface Functions */
+/**
+ * nautilus_location_widget_provider_get_widget:
+ * @provider: a #NautilusLocationWidgetProvider
+ * @uri: the URI of the location
+ * @window: parent #GtkWindow
+ *
+ * Returns: (transfer none): the location widget for @provider at @uri
+ */
 GtkWidget *nautilus_location_widget_provider_get_widget (NautilusLocationWidgetProvider *provider,
                                                          const char                     *uri,
                                                          GtkWidget                      *window);
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS
diff --git a/libnautilus-extension/nautilus-menu-item.c b/libnautilus-extension/nautilus-menu-item.c
index 85c8b8a72..ead7ee8ca 100644
--- a/libnautilus-extension/nautilus-menu-item.c
+++ b/libnautilus-extension/nautilus-menu-item.c
@@ -59,30 +59,6 @@ enum
 
 static guint signals[LAST_SIGNAL];
 
-/**
- * SECTION:nautilus-menu-item
- * @title: NautilusMenuItem
- * @short_description: Menu item descriptor object
- *
- * #NautilusMenuItem is an object that describes an item in a file manager
- * menu. Extensions can provide #NautilusMenuItem objects by registering a
- * #NautilusMenuProvider and returning them from
- * nautilus_menu_provider_get_file_items(), or
- * nautilus_menu_provider_get_background_items(), which will be called by the
- * main application when creating menus.
- */
-
-/**
- * nautilus_menu_item_new:
- * @name: the identifier for the menu item
- * @label: the user-visible label of the menu item
- * @tip: the tooltip of the menu item
- * @icon: the name of the icon to display in the menu item
- *
- * Creates a new menu item that can be added to the toolbar or to a contextual menu.
- *
- * Returns: a newly create #NautilusMenuItem
- */
 NautilusMenuItem *
 nautilus_menu_item_new (const char *name,
                         const char *label,
@@ -105,12 +81,6 @@ nautilus_menu_item_new (const char *name,
     return item;
 }
 
-/**
- * nautilus_menu_item_activate:
- * @item: pointer to a #NautilusMenuItem
- *
- * emits the activate signal.
- */
 void
 nautilus_menu_item_activate (NautilusMenuItem *self)
 {
@@ -119,13 +89,6 @@ nautilus_menu_item_activate (NautilusMenuItem *self)
     g_signal_emit (self, signals[ACTIVATE], 0);
 }
 
-/**
- * nautilus_menu_item_set_submenu:
- * @item: pointer to a #NautilusMenuItem
- * @menu: pointer to a #NautilusMenu to attach to the button
- *
- * Attachs a menu to the given #NautilusMenuItem.
- */
 void
 nautilus_menu_item_set_submenu (NautilusMenuItem *self,
                                 NautilusMenu     *menu)
@@ -317,6 +280,12 @@ nautilus_menu_item_class_init (NautilusMenuItemClass *class)
     G_OBJECT_CLASS (class)->get_property = nautilus_menu_item_get_property;
     G_OBJECT_CLASS (class)->set_property = nautilus_menu_item_set_property;
 
+    /**
+     * NautilusMenuItem::activate:
+     * @item: the object which received the signal
+     *
+     * Signals that the user has activated this menu item.
+     */
     signals[ACTIVATE] =
         g_signal_new ("activate",
                       G_TYPE_FROM_CLASS (class),
diff --git a/libnautilus-extension/nautilus-menu-provider.c b/libnautilus-extension/nautilus-menu-provider.c
index ead742bd7..5c7d40df6 100644
--- a/libnautilus-extension/nautilus-menu-provider.c
+++ b/libnautilus-extension/nautilus-menu-provider.c
@@ -35,15 +35,6 @@ enum
 
 static guint signals[LAST_SIGNAL];
 
-/**
- * SECTION:nautilus-menu-provider
- * @title: NautilusMenuProvider
- * @short_description: Interface to provide additional menu items
- *
- * #NautilusMenuProvider allows extension to provide additional menu items
- * in the file manager menus.
- */
-
 static void
 nautilus_menu_provider_default_init (NautilusMenuProviderInterface *klass)
 {
@@ -57,14 +48,6 @@ nautilus_menu_provider_default_init (NautilusMenuProviderInterface *klass)
                                            G_TYPE_NONE, 0);
 }
 
-/**
- * nautilus_menu_provider_get_file_items:
- * @provider: a #NautilusMenuProvider
- * @window: the parent #GtkWidget window
- * @files: (element-type NautilusFileInfo): a list of #NautilusFileInfo
- *
- * Returns: (element-type NautilusMenuItem) (transfer full): the provided list of #NautilusMenuItem
- */
 GList *
 nautilus_menu_provider_get_file_items (NautilusMenuProvider *provider,
                                        GtkWidget            *window,
@@ -85,14 +68,6 @@ nautilus_menu_provider_get_file_items (NautilusMenuProvider *provider,
     return NULL;
 }
 
-/**
- * nautilus_menu_provider_get_background_items:
- * @provider: a #NautilusMenuProvider
- * @window: the parent #GtkWidget window
- * @current_folder: the folder for which background items are requested
- *
- * Returns: (element-type NautilusMenuItem) (transfer full): the provided list of #NautilusMenuItem
- */
 GList *
 nautilus_menu_provider_get_background_items (NautilusMenuProvider *provider,
                                              GtkWidget            *window,
@@ -114,7 +89,6 @@ nautilus_menu_provider_get_background_items (NautilusMenuProvider *provider,
     return NULL;
 }
 
-/* This function emit a signal to inform nautilus that its item list has changed */
 void
 nautilus_menu_provider_emit_items_updated_signal (NautilusMenuProvider *provider)
 {
diff --git a/libnautilus-extension/nautilus-menu-provider.h b/libnautilus-extension/nautilus-menu-provider.h
index 311e2c10f..ca64ab266 100644
--- a/libnautilus-extension/nautilus-menu-provider.h
+++ b/libnautilus-extension/nautilus-menu-provider.h
@@ -51,12 +51,21 @@ G_DECLARE_INTERFACE (NautilusMenuProvider, nautilus_menu_provider,
 typedef NautilusMenuProviderInterface NautilusMenuProviderIface;
 
 /**
+ * SECTION:nautilus-menu-provider
+ * @title: NautilusMenuProvider
+ * @short_description: Interface to provide additional menu items
+ *
+ * #NautilusMenuProvider allows extension to provide additional menu items
+ * in the file manager menus.
+ */
+
+/**
  * NautilusMenuProviderInterface:
  * @g_iface: The parent interface.
  * @get_file_items: Returns a #GList of #NautilusMenuItem.
- *   See nautilus_menu_provider_get_file_items() for details.
+ *                  See nautilus_menu_provider_get_file_items() for details.
  * @get_background_items: Returns a #GList of #NautilusMenuItem.
- *   See nautilus_menu_provider_get_background_items() for details.
+ *                        See nautilus_menu_provider_get_background_items() for details.
  *
  * Interface for extensions to provide additional menu items.
  */
@@ -72,15 +81,35 @@ struct _NautilusMenuProviderInterface
                                     NautilusFileInfo     *current_folder);
 };
 
-/* Interface Functions */
+/**
+ * nautilus_menu_provider_get_file_items:
+ * @provider: a #NautilusMenuProvider
+ * @window: the parent #GtkWidget window
+ * @files: (element-type NautilusFileInfo): a list of #NautilusFileInfo
+ *
+ * Returns: (nullable) (element-type NautilusMenuItem) (transfer full): the provided list of #NautilusMenuItem.
+ */
 GList  *nautilus_menu_provider_get_file_items           (NautilusMenuProvider *provider,
                                                          GtkWidget            *window,
                                                          GList                *files);
+/**
+ * nautilus_menu_provider_get_background_items:
+ * @provider: a #NautilusMenuProvider
+ * @window: the parent #GtkWidget window
+ * @current_folder: the folder for which background items are requested
+ *
+ * Returns: (nullable) (element-type NautilusMenuItem) (transfer full): the provided list of #NautilusMenuItem.
+ */
 GList *nautilus_menu_provider_get_background_items      (NautilusMenuProvider *provider,
                                                          GtkWidget            *window,
                                                          NautilusFileInfo     *current_folder);
 
-/* This function emit a signal to inform nautilus that its item list has changed. */
+/**
+ * nautilus_menu_provider_emit_items_updated_signal:
+ * @provider: a #NautilusMenuProvider
+ *
+ * Emits #NautilusMenuProvider::items-updated.
+ */
 void   nautilus_menu_provider_emit_items_updated_signal (NautilusMenuProvider *provider);
 
 G_END_DECLS
diff --git a/libnautilus-extension/nautilus-menu.c b/libnautilus-extension/nautilus-menu.c
index d4b5b3001..34eab8fc2 100644
--- a/libnautilus-extension/nautilus-menu.c
+++ b/libnautilus-extension/nautilus-menu.c
@@ -26,16 +26,6 @@
 #include <glib.h>
 #include <glib/gi18n-lib.h>
 
-/**
- * SECTION:nautilus-menu
- * @title: NautilusMenu
- * @short_description: Menu descriptor object
- *
- * #NautilusMenu is an object that describes a submenu in a file manager
- * menu. Extensions can provide #NautilusMenu objects by attaching them to
- * #NautilusMenuItem objects, using nautilus_menu_item_set_submenu().
- */
-
 struct _NautilusMenu
 {
     GObject parent_instance;
@@ -55,12 +45,6 @@ nautilus_menu_append_item (NautilusMenu     *self,
     self->item_list = g_list_append (self->item_list, g_object_ref (menu_item));
 }
 
-/**
- * nautilus_menu_get_items:
- * @menu: a #NautilusMenu
- *
- * Returns: (element-type NautilusMenuItem) (transfer full): the provided #NautilusMenuItem list
- */
 GList *
 nautilus_menu_get_items (NautilusMenu *self)
 {
@@ -74,11 +58,6 @@ nautilus_menu_get_items (NautilusMenu *self)
     return item_list;
 }
 
-/**
- * nautilus_menu_item_list_free:
- * @item_list: (element-type NautilusMenuItem): a list of #NautilusMenuItem
- *
- */
 void
 nautilus_menu_item_list_free (GList *item_list)
 {
@@ -88,8 +67,6 @@ nautilus_menu_item_list_free (GList *item_list)
     g_list_free (item_list);
 }
 
-/* Type initialization */
-
 static void
 nautilus_menu_finalize (GObject *object)
 {
@@ -114,8 +91,6 @@ nautilus_menu_class_init (NautilusMenuClass *klass)
     object_class->finalize = nautilus_menu_finalize;
 }
 
-/* public constructors */
-
 NautilusMenu *
 nautilus_menu_new (void)
 {
diff --git a/libnautilus-extension/nautilus-menu.h b/libnautilus-extension/nautilus-menu.h
index bbf71fa88..d699e1c95 100644
--- a/libnautilus-extension/nautilus-menu.h
+++ b/libnautilus-extension/nautilus-menu.h
@@ -44,6 +44,25 @@ G_DECLARE_DERIVABLE_TYPE (NautilusMenuItem, nautilus_menu_item,
                           NAUTILUS, MENU_ITEM,
                           GObject)
 
+/**
+ * SECTION:nautilus-menu
+ * @title: NautilusMenu
+ * @short_description: Menu descriptor object
+ *
+ * #NautilusMenu is an object that describes a submenu in a file manager
+ * menu. Extensions can provide #NautilusMenu objects by attaching them to
+ * #NautilusMenuItem objects, using nautilus_menu_item_set_submenu().
+ *
+ * ## Menu Items
+ *
+ * #NautilusMenuItem is an object that describes an item in a file manager
+ * menu. Extensions can provide #NautilusMenuItem objects by registering a
+ * #NautilusMenuProvider and returning them from
+ * nautilus_menu_provider_get_file_items(), or
+ * nautilus_menu_provider_get_background_items(), which will be called by the
+ * main application when creating menus.
+ */
+
 struct _NautilusMenuItemClass
 {
     GObjectClass parent;
@@ -51,20 +70,64 @@ struct _NautilusMenuItemClass
     void (*activate) (NautilusMenuItem *item);
 };
 
+/**
+ * nautilus_menu_new:
+ *
+ * Returns: a new #NautilusMenu.
+ */
 NautilusMenu     *nautilus_menu_new              (void);
 
+/**
+ * nautilus_menu_append_item:
+ * @menu: a #NautilusMenu
+ * @item: (transfer full): a #NautilusMenuItem to append
+ */
 void              nautilus_menu_append_item      (NautilusMenu     *menu,
                                                   NautilusMenuItem *item);
+/**
+ * nautilus_menu_get_items:
+ * @menu: a #NautilusMenu
+ *
+ * Returns: (element-type NautilusMenuItem) (transfer full): the provided #NautilusMenuItem list
+ */
 GList            *nautilus_menu_get_items        (NautilusMenu     *menu);
+/**
+ * nautilus_menu_item_list_free:
+ * @item_list: (element-type NautilusMenuItem): a list of #NautilusMenuItem
+ *
+ */
 void              nautilus_menu_item_list_free   (GList            *item_list);
 
-
+/**
+ * nautilus_menu_item_new:
+ * @name: the identifier for the menu item
+ * @label: the user-visible label of the menu item
+ * @tip: the tooltip of the menu item
+ * @icon: the name of the icon to display in the menu item
+ *
+ * Creates a new menu item that can be added to the toolbar or to a contextual menu.
+ *
+ * Returns: (transfer full): a new #NautilusMenuItem
+ */
 NautilusMenuItem *nautilus_menu_item_new         (const char       *name,
                                                   const char       *label,
                                                   const char       *tip,
                                                   const char       *icon);
 
+/**
+ * nautilus_menu_item_activate:
+ * @item: pointer to a #NautilusMenuItem
+ *
+ * Emits #NautilusMenuItem::activate.
+ */
 void              nautilus_menu_item_activate    (NautilusMenuItem *item);
+/**
+ * nautilus_menu_item_set_submenu:
+ * @item: pointer to a #NautilusMenuItem
+ * @menu: (transfer full): pointer to a #NautilusMenu to attach to the button
+ *
+ * Attaches a menu to the given #NautilusMenuItem.
+ */
 void              nautilus_menu_item_set_submenu (NautilusMenuItem *item,
                                                   NautilusMenu     *menu);
 
@@ -79,4 +142,4 @@ void              nautilus_menu_item_set_submenu (NautilusMenuItem *item,
  *   menu (NautilusMenu)  - The menu belonging to this item. May be null.
  */
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS
diff --git a/libnautilus-extension/nautilus-property-page-provider.c b/libnautilus-extension/nautilus-property-page-provider.c
index 26ec03cf5..45b2daf85 100644
--- a/libnautilus-extension/nautilus-property-page-provider.c
+++ b/libnautilus-extension/nautilus-property-page-provider.c
@@ -27,33 +27,11 @@
 G_DEFINE_INTERFACE (NautilusPropertyPageProvider, nautilus_property_page_provider,
                     G_TYPE_OBJECT)
 
-/**
- * SECTION:nautilus-property-page-provider
- * @title: NautilusPropertyPageProvider
- * @short_description: Interface to provide additional property pages
- *
- * #NautilusPropertyPageProvider allows extension to provide additional pages
- * for the file properties dialog.
- */
-
 static void
 nautilus_property_page_provider_default_init (NautilusPropertyPageProviderInterface *klass)
 {
 }
 
-/**
- * nautilus_property_page_provider_get_pages:
- * @provider: a #NautilusPropertyPageProvider
- * @files: (element-type NautilusFileInfo): a #GList of #NautilusFileInfo
- *
- * This function is called by Nautilus when it wants property page
- * items from the extension.
- *
- * This function is called in the main thread before a property page
- * is shown, so it should return quickly.
- *
- * Returns: (element-type NautilusPropertyPage) (transfer full): A #GList of allocated #NautilusPropertyPage items.
- */
 GList *
 nautilus_property_page_provider_get_pages (NautilusPropertyPageProvider *self,
                                            GList                        *files)
diff --git a/libnautilus-extension/nautilus-property-page-provider.h b/libnautilus-extension/nautilus-property-page-provider.h
index e3c9416f8..61bcd8b63 100644
--- a/libnautilus-extension/nautilus-property-page-provider.h
+++ b/libnautilus-extension/nautilus-property-page-provider.h
@@ -52,6 +52,15 @@ G_DECLARE_INTERFACE (NautilusPropertyPageProvider, nautilus_property_page_provid
 typedef NautilusPropertyPageProviderInterface NautilusPropertyPageProviderIface;
 
 /**
+ * SECTION:nautilus-property-page-provider
+ * @title: NautilusPropertyPageProvider
+ * @short_description: Interface to provide additional property pages
+ *
+ * #NautilusPropertyPageProvider allows extension to provide additional pages
+ * for the file properties dialog.
+ */
+
+/**
  * NautilusPropertyPageProviderInterface:
  * @g_iface: The parent interface.
  * @get_pages: Returns a #GList of #NautilusPropertyPage.
@@ -67,8 +76,20 @@ struct _NautilusPropertyPageProviderInterface
                          GList                        *files);
 };
 
-/* Interface Functions */
+/**
+ * nautilus_property_page_provider_get_pages:
+ * @provider: a #NautilusPropertyPageProvider
+ * @files: (element-type NautilusFileInfo): a #GList of #NautilusFileInfo
+ *
+ * This function is called by Nautilus when it wants property page
+ * items from the extension.
+ *
+ * This function is called in the main thread before a property page
+ * is shown, so it should return quickly.
+ *
+ * Returns: (element-type NautilusPropertyPage) (transfer full): A #GList of allocated #NautilusPropertyPage items.
+ */
 GList *nautilus_property_page_provider_get_pages (NautilusPropertyPageProvider *provider,
                                                   GList                        *files);
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS
diff --git a/libnautilus-extension/nautilus-property-page.c b/libnautilus-extension/nautilus-property-page.c
index ca81fc121..dad8e5315 100644
--- a/libnautilus-extension/nautilus-property-page.c
+++ b/libnautilus-extension/nautilus-property-page.c
@@ -46,28 +46,6 @@ struct _NautilusPropertyPage
 
 G_DEFINE_TYPE (NautilusPropertyPage, nautilus_property_page, G_TYPE_OBJECT)
 
-/**
- * SECTION:nautilus-property-page
- * @title: NautilusPropertyPage
- * @short_description: Property page descriptor object
- *
- * #NautilusPropertyPage is an object that describes a page in the file
- * properties dialog. Extensions can provide #NautilusPropertyPage objects
- * by registering a #NautilusPropertyPageProvider and returning them from
- * nautilus_property_page_provider_get_pages(), which will be called by the
- * main application when creating file properties dialogs.
- */
-
-/**
- * nautilus_property_page_new:
- * @name: the identifier for the property page
- * @label: the user-visible label of the property page
- * @page: the property page to display
- *
- * Creates a new #NautilusPropertyPage from page_widget.
- *
- * Returns: a newly created #NautilusPropertyPage
- */
 NautilusPropertyPage *
 nautilus_property_page_new (const char *name,
                             GtkWidget  *label,
diff --git a/libnautilus-extension/nautilus-property-page.h b/libnautilus-extension/nautilus-property-page.h
index 70e31925a..1177f79d6 100644
--- a/libnautilus-extension/nautilus-property-page.h
+++ b/libnautilus-extension/nautilus-property-page.h
@@ -40,6 +40,26 @@ G_DECLARE_FINAL_TYPE (NautilusPropertyPage, nautilus_property_page,
                       NAUTILUS, PROPERTY_PAGE,
                       GObject)
 
+/**
+ * SECTION:nautilus-property-page
+ * @title: NautilusPropertyPage
+ * @short_description: Property page descriptor object
+ *
+ * #NautilusPropertyPage is an object that describes a page in the file
+ * properties dialog. Extensions can provide #NautilusPropertyPage objects
+ * by registering a #NautilusPropertyPageProvider and returning them from
+ * nautilus_property_page_provider_get_pages(), which will be called by the
+ * main application when creating file properties dialogs.
+ */
+
+/**
+ * nautilus_property_page_new:
+ * @name: the identifier for the property page
+ * @label: the user-visible label of the property page
+ * @page: the property page to display
+ *
+ * Returns: (transfer full): a new #NautilusPropertyPage
+ */
 NautilusPropertyPage *nautilus_property_page_new (const char *name,
                                                   GtkWidget  *label,
                                                   GtkWidget  *page);
@@ -50,4 +70,4 @@ NautilusPropertyPage *nautilus_property_page_new (const char *name,
  *   page (widget)        - the property page to display
  */
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS