doc: gir annotations cleanup

- @skip -> @girskip
- @null -> @nullable
- @addtogir -> @gironly
- changed internal xml representation of @cb, @cbdata, @cbfree
- @girskip keybindings_set_item() too

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

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,' \

src/editor.h

@@ -50,7 +50,7 @@ typedef enum
 }
 GeanyIndentType;
 
-/** @addtogir
+/** @gironly
  * Auto indentation modes */
 typedef enum
 {

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.

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.

src/search.h

@@ -43,7 +43,7 @@ typedef enum GeanyFindFlags
 }
 GeanyFindFlags;
 
-/** @addtogir
+/** @gironly
  * Find selection options */
 typedef enum
 {

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,

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)

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.