doc: gir annotations cleanup

- @skip -> @girskip - @null -> @nullable - @addtogir -> @gironly - changed internal xml representation of @cb, @cbdata, @cbfree - @girskip keybindings_set_item() too
2016-02-15 21:14:16 +01:00 · 2016-02-15 21:14:16 +01:00 · f2ebd288b3
commit f2ebd288b3
parent c35f29ae36
9 changed files with 38 additions and 36 deletions
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@ -248,16 +248,16 @@ ALIASES                = "signal=- @ref  " \
                         "signaldesc=" \
                         "signals=@b Signals:  " \
                         "endsignals=  " \
-                         "addtogir=@internal"
+                         "gironly=@internal"

 ALIASES               += "transfer{1}=\a \xmlonly <simplesect kind=\"geany:transfer\">\1</simplesect>\endxmlonly \htmlonly (transfer: \1) \endhtmlonly"
 ALIASES               += "elementtype{1}=\a \xmlonly <simplesect kind=\"geany:element-type\">\1</simplesect>\endxmlonly \htmlonly (element-type: \1) \endhtmlonly"
 ALIASES               += "scope{1}=\a \xmlonly <simplesect kind=\"geany:scope\">\1</simplesect>\endxmlonly \htmlonly (scope: \1) \endhtmlonly"
-ALIASES               += "skip=\a \xmlonly <simplesect kind=\"geany:skip\"></simplesect>\endxmlonly"
-ALIASES               += "null=\a \xmlonly <simplesect kind=\"geany:nullable\"></simplesect>\endxmlonly"
-ALIASES               += "cb=\a \xmlonly <simplesect kind=\"geany:cb\"></simplesect>\endxmlonly"
-ALIASES               += "cbdata=\a \xmlonly <simplesect kind=\"geany:cbdata\"></simplesect>\endxmlonly"
-ALIASES               += "cbfree=\a \xmlonly <simplesect kind=\"geany:cbfree\"></simplesect>\endxmlonly"
+ALIASES               += "girskip=\a \xmlonly <simplesect kind=\"geany:skip\"></simplesect>\endxmlonly"
+ALIASES               += "nullable=\a \xmlonly <simplesect kind=\"geany:nullable\"></simplesect>\endxmlonly"
+ALIASES               += "cb=\a \xmlonly <simplesect kind=\"geany:scope\">notified</simplesect>\endxmlonly"
+ALIASES               += "cbdata=\a \xmlonly <simplesect kind=\"geany:closure\"></simplesect>\endxmlonly"
+ALIASES               += "cbfree=\a \xmlonly <simplesect kind=\"geany:destroy\"></simplesect>\endxmlonly"


 # This tag can be used to specify a number of word-keyword mappings (TCL only).
@ -845,8 +845,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.

-EXCLUDE                = @top_srcdir@/doc/geany-gtkdoc.h \
-                         @top_srcdir@/doc/geany-scintilla-gtkdoc.h
+EXCLUDE                = @top_srcdir@/doc/geany-gtkdoc.h

 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@ -104,7 +104,7 @@ doxygen_sources = \
 # for xml output
 Doxyfile-gi: Doxyfile
 	$(AM_V_GEN)$(SED) \
-		-e 's,addtogir=@internal,addtogir=,' \
+		-e 's,gironly=@internal,gironly=,' \
 		-e 's,^\(GENERATE_HTML.*\)YES,\1NO,' \
 		-e 's,^\(GENERATE_XML.*\)NO,\1YES,' \
 		-e 's,^\(WARN_IF_UNDOCUMENTED.*\)YES,\1NO,' \
--- a/src/editor.h
+++ b/src/editor.h
@ -50,7 +50,7 @@ typedef enum
 }
 GeanyIndentType;

-/** @addtogir
+/** @gironly
 * Auto indentation modes */
 typedef enum
 {
--- a/src/keybindings.c
+++ b/src/keybindings.c
@ -150,7 +150,8 @@ GeanyKeyBinding *keybindings_get_item(GeanyKeyGroup *group, gsize key_id)

 /* This is used to set default keybindings on startup.
 * Menu accels are set in apply_kb_accel(). */
-/** Fills a GeanyKeyBinding struct item.
+/** @girskip
+ * Fills a GeanyKeyBinding struct item.
 * @note Always set @a key and @a mod to 0, otherwise you will likely
 * cause conflicts with the user's custom, other plugin's keybindings or
 * future default keybindings.
@ -216,8 +217,8 @@ GeanyKeyBinding *keybindings_set_item(GeanyKeyGroup *group, gsize key_id,
 * @param kf_name Key name for the configuration file, such as @c "menu_new".
 * @param label Label used in the preferences dialog keybindings tab. May contain
 * underscores - these won't be displayed.
- * @param menu_item @null Optional widget to set an accelerator for, or @c NULL.
- * @param cb @null New-style callback to be called when activated, or @c NULL to use the group callback.
+ * @param menu_item @nullable Optional widget to set an accelerator for.
+ * @param cb @nullable New-style callback to be called when activated, or @c NULL to use the group callback.
 * @param pdata Plugin-specific data passed back to the callback @a cb.
 * @param destroy_notify Function that is invoked to free the plugin data when not needed anymore.
 * @return @transfer{none} The keybinding - normally this is ignored.
--- a/src/pluginutils.c
+++ b/src/pluginutils.c
@ -102,7 +102,8 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
 }


-/** Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
+/** @girskip
+ * Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
 * @param plugin Must be @ref geany_plugin.
 * @param object Object to connect to, or @c NULL when using @link pluginsignals.c Geany signals @endlink.
 * @param signal_name The name of the signal. For a list of available
@ -129,7 +130,6 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
 * @note Since version 1.25 (API >= 218), the object lifetime is watched and so the above
 *       restriction does not apply.  However, for objects destroyed by the plugin,
 *       @c g_signal_connect() is safe and has lower overhead.
- * @skip
 **/
 GEANY_API_SYMBOL
 void plugin_signal_connect(GeanyPlugin *plugin,
@ -231,8 +231,9 @@ static guint plugin_source_add(GeanyPlugin *plugin, GSource *source, GSourceFunc
 }


-/** Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
- *  preventing it to run after the plugin has been unloaded (which may lead to a segfault).
+/** @girskip
+ * Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
+ * preventing it to run after the plugin has been unloaded (which may lead to a segfault).
 *
 * @param plugin Must be @ref geany_plugin.
 * @param interval The time between calls to the function, in milliseconds.
@ -243,7 +244,6 @@ static guint plugin_source_add(GeanyPlugin *plugin, GSource *source, GSourceFunc
 *
 * @see g_timeout_add()
 * @since 0.21, plugin API 205.
- * @skip
 */
 GEANY_API_SYMBOL
 guint plugin_timeout_add(GeanyPlugin *plugin, guint interval, GSourceFunc function, gpointer data)
@ -252,8 +252,9 @@ guint plugin_timeout_add(GeanyPlugin *plugin, guint interval, GSourceFunc functi
 }


-/** Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
- *  preventing it to run after the plugin has been unloaded (which may lead to a segfault).
+/** @girskip
+ * Adds a GLib main loop timeout callback that will be removed when unloading the plugin,
+ * preventing it to run after the plugin has been unloaded (which may lead to a segfault).
 *
 * @param plugin Must be @ref geany_plugin.
 * @param interval The time between calls to the function, in seconds.
@ -264,7 +265,6 @@ guint plugin_timeout_add(GeanyPlugin *plugin, guint interval, GSourceFunc functi
 *
 * @see g_timeout_add_seconds()
 * @since 0.21, plugin API 205.
- * @skip
 */
 GEANY_API_SYMBOL
 guint plugin_timeout_add_seconds(GeanyPlugin *plugin, guint interval, GSourceFunc function,
@ -274,8 +274,9 @@ guint plugin_timeout_add_seconds(GeanyPlugin *plugin, guint interval, GSourceFun
 }


-/** Adds a GLib main loop IDLE callback that will be removed when unloading the plugin, preventing
- *  it to run after the plugin has been unloaded (which may lead to a segfault).
+/** @girskip
+ * Adds a GLib main loop IDLE callback that will be removed when unloading the plugin, preventing
+ * it to run after the plugin has been unloaded (which may lead to a segfault).
 *
 * @param plugin Must be @ref geany_plugin.
 * @param function The function to call in IDLE time.
@ -285,7 +286,6 @@ guint plugin_timeout_add_seconds(GeanyPlugin *plugin, guint interval, GSourceFun
 *
 * @see g_idle_add()
 * @since 0.21, plugin API 205.
- * @skip
 */
 GEANY_API_SYMBOL
 guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data)
@ -294,7 +294,8 @@ guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data)
 }


-/** Sets up or resizes a keybinding group for the plugin.
+/** @girskip
+ * Sets up or resizes a keybinding group for the plugin.
 * You should then call keybindings_set_item() for each keybinding in the group.
 * @param plugin Must be @ref geany_plugin.
 * @param section_name Name used in the configuration file, such as @c "html_chars".
@ -302,7 +303,7 @@ guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data)
 * @param callback Group callback, or @c NULL if you only want individual keybinding callbacks.
 * @return The plugin's keybinding group.
 * @since 0.19.
- * @skip */
+ **/
 GEANY_API_SYMBOL
 GeanyKeyGroup *plugin_set_key_group(GeanyPlugin *plugin,
 		const gchar *section_name, gsize count, GeanyKeyGroupCallback callback)
@ -321,7 +322,7 @@ GeanyKeyGroup *plugin_set_key_group(GeanyPlugin *plugin,
 * @param plugin Must be @ref geany_plugin.
 * @param section_name Name used in the configuration file, such as @c "html_chars".
 * @param count Number of keybindings for the group.
- * @param cb @null New-style group callback, or @c NULL if you only want individual keybinding callbacks.
+ * @param cb @nullable New-style group callback, or @c NULL if you only want individual keybinding callbacks.
 * @param pdata Plugin specific data, passed to the group callback @a cb.
 * @param destroy_notify Function that is invoked to free the plugin data when not needed anymore.
 * @return @transfer{none} The plugin's keybinding group.
--- a/src/search.h
+++ b/src/search.h
@ -43,7 +43,7 @@ typedef enum GeanyFindFlags
 }
 GeanyFindFlags;

-/** @addtogir
+/** @gironly
 * Find selection options */
 typedef enum
 {
--- a/src/spawn.c
+++ b/src/spawn.c
@ -950,7 +950,7 @@ static void spawn_watch_cb(GPid pid, gint status, gpointer data)
 }


-/**
+/** @girskip
 *  Executes a child program and setups callbacks.
 *
 *  A command line or an argument vector must be passed. If both are present, the argument
@ -999,7 +999,6 @@ static void spawn_watch_cb(GPid pid, gint status, gpointer data)
 *  @return @c TRUE on success, @c FALSE on error.
 *
 *  @since 1.25
- *  @skip
 **/
 GEANY_API_SYMBOL
 gboolean spawn_with_callbacks(const gchar *working_directory, const gchar *command_line,
--- a/src/ui_utils.c
+++ b/src/ui_utils.c
@ -2843,14 +2843,15 @@ GtkWidget *ui_label_new_bold(const gchar *text)
 }


-/** Adds a list of document items to @a menu.
+/** @girskip
+ * Adds a list of document items to @a menu.
 * @param menu Menu.
 * @param active Which document to highlight, or @c NULL.
 * @param callback is used for each menu item's @c "activate" signal and will be
 * passed the corresponding document pointer as @c user_data.
 * @warning You should check @c doc->is_valid in the callback.
 * @since 0.19
- * @skip */
+ **/
 GEANY_API_SYMBOL
 void ui_menu_add_document_items(GtkMenu *menu, GeanyDocument *active, GCallback callback)
 {
@ -2858,7 +2859,8 @@ void ui_menu_add_document_items(GtkMenu *menu, GeanyDocument *active, GCallback
 }


-/** Adds a list of document items to @a menu.
+/** @girskip
+ * Adds a list of document items to @a menu.
 *
 * @a compare_func might be NULL to not sort the documents in the menu. In this case,
 * the order of the document tabs is used.
@ -2872,7 +2874,7 @@ void ui_menu_add_document_items(GtkMenu *menu, GeanyDocument *active, GCallback
 * @param compare_func is used to sort the list. Might be @c NULL to not sort the list.
 * @warning You should check @c doc->is_valid in the callback.
 * @since 0.21
- * @skip */
+ **/
 GEANY_API_SYMBOL
 void ui_menu_add_document_items_sorted(GtkMenu *menu, GeanyDocument *active,
 	GCallback callback, GCompareFunc compare_func)
--- a/src/utils.c
+++ b/src/utils.c
@ -1651,7 +1651,7 @@ const gchar *utils_get_default_dir_utf8(void)
 *  @param argv The child's argument vector.
 *  @param env The child's environment, or @c NULL to inherit parent's.
 *  @param flags Ignored.
- *  @param child_setup @skip Ignored.
+ *  @param child_setup @girskip Ignored.
 *  @param user_data Ignored.
 *  @param std_out The return location for child output, or @c NULL.
 *  @param std_err The return location for child error messages, or @c NULL.
@ -1686,7 +1686,7 @@ gboolean utils_spawn_sync(const gchar *dir, gchar **argv, gchar **env, GSpawnFla
 *  @param argv The child's argument vector.
 *  @param env The child's environment, or @c NULL to inherit parent's.
 *  @param flags Ignored.
- *  @param child_setup @skip Ignored.
+ *  @param child_setup @girskip Ignored.
 *  @param user_data Ignored.
 *  @param child_pid The return location for child process ID, or NULL.
 *  @param error The return location for error or @c NULL.