Clean up GApplication docs

Clean up the docs for GApplication and related classes.

I'm no longer writing documentation for the structure type of classes
and interfaces.  See https://bugzilla.gnome.org/show_bug.cgi?id=665926
for discussin on the correct way forward on this point.

Also: stop putting gtk-doc comments in installed headers.

diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 6e1c5d7..39cec80 100644 (file)
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2879,6 +2879,7 @@ g_application_command_line_get_type
 <FILE>gactiongroup</FILE>
 <TITLE>GActionGroup</TITLE>
 GActionGroup
+GActionGroupInterface
 
 <SUBSECTION>
 g_action_group_list_actions
@@ -2937,7 +2938,7 @@ g_dbus_action_group_get_type
 <FILE>gaction</FILE>
 <TITLE>GAction</TITLE>
 GAction
-
+GActionInterface
 
 <SUBSECTION>
 g_action_get_name
@@ -3013,6 +3014,7 @@ G_SIMPLE_ACTION_GROUP
 <FILE>gactionmap</FILE>
 <TITLE>GActionMap</TITLE>
 GActionMap
+GActionMapInterface
 g_action_map_lookup_action
 GActionEntry
 g_action_map_add_action_entries

diff --git a/gio/Makefile.am b/gio/Makefile.am
index ef5df51..7779e6c 100644 (file)
--- a/gio/Makefile.am
+++ b/gio/Makefile.am
@@ -125,39 +125,43 @@ settings_sources += \
 endif
 
 application_headers = \
+       gapplication.h                  \
+       gapplicationcommandline.h       \
+                                       \
        gactiongroup.h                  \
        gactionmap.h                    \
        gsimpleactiongroup.h            \
+       gactiongroupexporter.h          \
+       gdbusactiongroup.h              \
        gaction.h                       \
        gsimpleaction.h                 \
-       gdbusactiongroup.h              \
-       gactiongroupexporter.h          \
-       gapplicationcommandline.h       \
-       gapplication.h                  \
+                                       \
        gmenumodel.h                    \
-       gdbusmenumodel.h                \
-       gmenu.h                         \
        gmenumarkup.h                   \
+       gmenu.h                         \
        gmenuexporter.h                 \
+       gdbusmenumodel.h                \
        $(NULL)
 
 application_sources = \
+       gapplication.c                          \
+       gapplicationcommandline.c               \
+       gapplicationimpl-dbus.c                 \
+       gapplicationimpl.h                      \
+                                               \
        gactiongroup.c                          \
        gactionmap.c                            \
        gsimpleactiongroup.c                    \
+       gactiongroupexporter.c                  \
+       gdbusactiongroup.c                      \
        gaction.c                               \
        gsimpleaction.c                         \
-       gdbusactiongroup.c                      \
-       gactiongroupexporter.c                  \
-       gapplicationcommandline.c               \
-       gapplicationimpl.h                      \
-       gapplicationimpl-dbus.c                 \
-       gapplication.c                          \
+                                               \
        gmenumodel.c                            \
-       gdbusmenumodel.c                        \
-       gmenu.c                                 \
        gmenumarkup.c                           \
+       gmenu.c                                 \
        gmenuexporter.c                         \
+       gdbusmenumodel.c                        \
        $(NULL)
 
 local_sources = \

diff --git a/gio/gaction.c b/gio/gaction.c
index 66e6dc9..18318b0 100644 (file)
--- a/gio/gaction.c
+++ b/gio/gaction.c
@@ -61,6 +61,23 @@ G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
  * inside of a #GSimpleActionGroup.
  **/
 
+/**
+ * GActionInterface:
+ * @get_name: the virtual function pointer for g_action_get_name()
+ * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
+ * @get_state_type: the virtual function pointer for g_action_get_state_type()
+ * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
+ * @get_enabled: the virtual function pointer for g_action_get_enabled()
+ * @get_state: the virtual function pointer for g_action_get_state()
+ * @change_state: the virtual function pointer for g_action_change_state()
+ * @activate: the virtual function pointer for g_action_activate().  Note that #GAction does not have an
+ *            'activate' signal but that implementations of it may have one.
+ *
+ * The virtual function table for #GAction.
+ *
+ * Since: 2.28
+ */
+
 void
 g_action_default_init (GActionInterface *iface)
 {

diff --git a/gio/gaction.h b/gio/gaction.h
index a0f3960..69e6a9a 100644 (file)
--- a/gio/gaction.h
+++ b/gio/gaction.h
@@ -39,20 +39,6 @@ G_BEGIN_DECLS
 
 typedef struct _GActionInterface                            GActionInterface;
 
-/**
- * GActionInterface:
- * @get_name: the virtual function pointer for g_action_get_name()
- * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
- * @get_state_type: the virtual function pointer for g_action_get_state_type()
- * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
- * @get_enabled: the virtual function pointer for g_action_get_enabled()
- * @get_state: the virtual function pointer for g_action_get_state()
- * @change_state: the virtual function pointer for g_action_change_state()
- * @activate: the virtual function pointer for g_action_activate().  Note that #GAction does not have an
- *            'activate' signal but that implementations of it may have one.
- *
- * Since: 2.28
- */
 struct _GActionInterface
 {
   GTypeInterface g_iface;

diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c
index 7559fb3..f7cd6e9 100644 (file)
--- a/gio/gactiongroup.c
+++ b/gio/gactiongroup.c
@@ -56,6 +56,29 @@
  * calls to g_action_group_query_action().
  **/
 
+/**
+ * GActionGroupInterface:
+ * @has_action: the virtual function pointer for g_action_group_has_action()
+ * @list_actions: the virtual function pointer for g_action_group_list_actions()
+ * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
+ * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
+ * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
+ * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
+ * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
+ * @set_action_state: the virtual function pointer for g_action_group_set_action_state()
+ * @query_action: the virtual function pointer for g_action_group_query_action()
+ * @activate_action: the virtual function pointer for g_action_group_activate_action()
+ * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
+ * @action_added: the class closure for the #GActionGroup::action-added signal
+ * @action_removed: the class closure for the #GActionGroup::action-removed signal
+ * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
+ * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
+ *
+ * The virtual function table for #GActionGroup.
+ *
+ * Since: 2.28
+ **/
+
 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
 
 enum

diff --git a/gio/gactiongroup.h b/gio/gactiongroup.h
index 6020776..b52006b 100644 (file)
--- a/gio/gactiongroup.h
+++ b/gio/gactiongroup.h
@@ -41,26 +41,6 @@ G_BEGIN_DECLS
 
 typedef struct _GActionGroupInterface                       GActionGroupInterface;
 
-/**
- * GActionGroupInterface:
- * @has_action: the virtual function pointer for g_action_group_has_action()
- * @list_actions: the virtual function pointer for g_action_group_list_actions()
- * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
- * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
- * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
- * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
- * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
- * @set_action_state: the virtual function pointer for g_action_group_set_action_state()
- * @activate_action: the virtual function pointer for g_action_group_activate_action()
- * @action_added: the class closure for the #GActionGroup::action-added signal
- * @action_removed: the class closure for the #GActionGroup::action-removed signal
- * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
- * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
- *
- * The virtual function table for #GActionGroup.
- *
- * Since: 2.28
- */
 struct _GActionGroupInterface
 {
   GTypeInterface g_iface;

diff --git a/gio/gactionmap.c b/gio/gactionmap.c
index 692c176..67feec8 100644 (file)
--- a/gio/gactionmap.c
+++ b/gio/gactionmap.c
@@ -40,7 +40,20 @@
  * prefixed names (e.g. by prepending "app." or "win.").
  * This is the motivation for the 'Map' part of the interface
  * name.
- */
+ *
+ * Since: 2.32
+ **/
+
+/**
+ * GActionMapInterface:
+ * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
+ * @add_action: the virtual function pointer for g_action_map_add_action()
+ * @remove_action: the virtual function pointer for g_action_map_remove_action()
+ *
+ * The virtual function table for #GActionMap.
+ *
+ * Since: 2.32
+ **/
 
 G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_ACTION_GROUP)
 

diff --git a/gio/gapplication.c b/gio/gapplication.c
index a562351..657e6cc 100644 (file)
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -159,6 +159,41 @@
  * </example>
  */
 
+/**
+ * GApplicationClass:
+ * @startup: invoked on the primary instance immediately after registration
+ * @shutdown: invoked only on the registered primary instance immediately
+ *      after the main loop terminates
+ * @activate: invoked on the primary instance when an activation occurs
+ * @open: invoked on the primary instance when there are files to open
+ * @command_line: invoked on the primary instance when a command-line is
+ *   not handled locally
+ * @local_command_line: invoked (locally) when the process has been invoked
+ *     via commandline execution (as opposed to, say, D-Bus activation - which
+ *     is not currently supported by GApplication). The virtual function has
+ *     the chance to inspect (and possibly replace) the list of command line
+ *     arguments. See g_application_run() for more information.
+ * @before_emit: invoked on the primary instance before 'activate', 'open',
+ *     'command-line' or any action invocation, gets the 'platform data' from
+ *     the calling instance
+ * @after_emit: invoked on the primary instance after 'activate', 'open',
+ *     'command-line' or any action invocation, gets the 'platform data' from
+ *     the calling instance
+ * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
+ *     the primary instance when activating, opening or invoking actions
+ * @quit_mainloop: Used to be invoked on the primary instance when the use
+ *     count of the application drops to zero (and after any inactivity
+ *     timeout, if requested). Not used anymore since 2.32
+ * @run_mainloop: Used to be invoked on the primary instance from
+ *     g_application_run() if the use-count is non-zero. Since 2.32,
+ *     GApplication is iterating the main context directly and is not
+ *     using @run_mainloop anymore
+ *
+ * Virtual function table for #GApplication.
+ *
+ * Since: 2.28
+ */
+
 struct _GApplicationPrivate
 {
   GApplicationFlags  flags;

diff --git a/gio/gapplication.h b/gio/gapplication.h
index 6fd4b2a..76fcf93 100644 (file)
--- a/gio/gapplication.h
+++ b/gio/gapplication.h
@@ -46,9 +46,6 @@ typedef struct _GApplicationClass                           GApplicationClass;
 /**
  * GApplication:
  *
- * The <structname>GApplication</structname> structure contains private
- * data and should only be accessed using the provided API
- *
  * Since: 2.28
  */
 struct _GApplication
@@ -59,38 +56,6 @@ struct _GApplication
   GApplicationPrivate *priv;
 };
 
-/**
- * GApplicationClass:
- * @startup: invoked on the primary instance immediately after registration
- * @shutdown: invoked only on the registered primary instance immediately
- *      after the main loop terminates
- * @activate: invoked on the primary instance when an activation occurs
- * @open: invoked on the primary instance when there are files to open
- * @command_line: invoked on the primary instance when a command-line is
- *   not handled locally
- * @local_command_line: invoked (locally) when the process has been invoked
- *     via commandline execution (as opposed to, say, D-Bus activation - which
- *     is not currently supported by GApplication). The virtual function has
- *     the chance to inspect (and possibly replace) the list of command line
- *     arguments. See g_application_run() for more information.
- * @before_emit: invoked on the primary instance before 'activate', 'open',
- *     'command-line' or any action invocation, gets the 'platform data' from
- *     the calling instance
- * @after_emit: invoked on the primary instance after 'activate', 'open',
- *     'command-line' or any action invocation, gets the 'platform data' from
- *     the calling instance
- * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
- *     the primary instance when activating, opening or invoking actions
- * @quit_mainloop: Used to be invoked on the primary instance when the use
- *     count of the application drops to zero (and after any inactivity
- *     timeout, if requested). Not used anymore since 2.32
- * @run_mainloop: Used to be invoked on the primary instance from
- *     g_application_run() if the use-count is non-zero. Since 2.32,
- *     GApplication is iterating the main context directly and is not
- *     using @run_mainloop anymore
- *
- * Since: 2.28
- */
 struct _GApplicationClass
 {
   /*< private >*/

diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index e7a5c6c..9497123 100644 (file)
--- a/gio/gapplicationcommandline.c
+++ b/gio/gapplicationcommandline.c
@@ -119,6 +119,14 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * </example>
  **/
 
+/**
+ * GApplicationCommandLineClass:
+ *
+ * The <structname>GApplicationCommandLineClass</structname> structure
+ * contains private data only
+ *
+ * Since: 2.28
+ **/
 enum
 {
   PROP_NONE,

diff --git a/gio/gapplicationcommandline.h b/gio/gapplicationcommandline.h
index 3d2093c..25def21 100644 (file)
--- a/gio/gapplicationcommandline.h
+++ b/gio/gapplicationcommandline.h
@@ -49,14 +49,6 @@ G_BEGIN_DECLS
 typedef struct _GApplicationCommandLinePrivate               GApplicationCommandLinePrivate;
 typedef struct _GApplicationCommandLineClass                 GApplicationCommandLineClass;
 
-/**
- * GApplicationCommandLine:
- *
- * The <structname>GApplicationCommandLine</structname> structure contains private
- * data and should only be accessed using the provided API
- *
- * Since: 2.28
- */
 struct _GApplicationCommandLine
 {
   /*< private >*/
@@ -65,14 +57,6 @@ struct _GApplicationCommandLine
   GApplicationCommandLinePrivate *priv;
 };
 
-/**
- * GApplicationCommandLineClass:
- *
- * The <structname>GApplicationCommandLineClass</structname> structure contains
- * private data only
- *
- * Since: 2.28
- */
 struct _GApplicationCommandLineClass
 {
   /*< private >*/