doxygen: various doxygen-related fixes in preparation for gtkdoc gene…

…ration

doc/Doxyfile.in

@@ -247,7 +247,18 @@ ALIASES                = "signal=- @ref  " \
                          "endsignalproto=@endcode  " \
                          "signaldesc=" \
                          "signals=@b Signals:  " \
-                         "endsignals=  "
+                         "endsignals=  " \
+                         "addtogir=@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"
+
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"

doc/pluginsymbols.c

@@ -87,7 +87,9 @@ KeyBindingGroup *plugin_key_group;
  * @param dialog The plugin preferences dialog widget - this should only be used to
  * connect the @c "response" signal. If settings should be read from the dialog, the
  * response will be either @c GTK_RESPONSE_OK or @c GTK_RESPONSE_APPLY.
- * @return A container widget holding preference widgets.
+ *
+ * @return @transfer{floating} A container widget holding preference widgets.
+ *
  * @note Using @link stash.h Stash @endlink can make implementing preferences easier.
  * @see plugin_configure_single(). */
 GtkWidget *plugin_configure(GtkDialog *dialog);

src/document.c

@@ -146,7 +146,7 @@ static GtkWidget* document_show_message(GeanyDocument *doc, GtkMessageType msgty
  * @param realname The filename to search, which should be identical to the
  * string returned by @c tm_get_real_path().
  *
- * @return The matching document, or @c NULL.
+ * @return @transfer{none} The matching document, or @c NULL.
  * @note This is only really useful when passing a @c TMSourceFile::file_name.
  * @see GeanyDocument::real_path.
  * @see document_find_by_filename().
@@ -196,7 +196,7 @@ static gchar *get_real_path_from_utf8(const gchar *utf8_filename)
  *
  *  @param utf8_filename The filename to search (in UTF-8 encoding).
  *
- *  @return The matching document, or @c NULL.
+ *  @return @transfer{none} The matching document, or @c NULL.
  *  @see document_find_by_real_path().
  **/
 GEANY_API_SYMBOL
@@ -250,7 +250,7 @@ GeanyDocument *document_find_by_sci(ScintillaObject *sci)
  * Useful when the corresponding document may have been closed since the
  * ID was retrieved.
  * @param id The ID of the document to find
- * @return @c NULL if the document is no longer open.
+ * @return @transfer{none} @c NULL if the document is no longer open.
  *
  * Example:
  * @code
@@ -366,7 +366,7 @@ GeanyDocument *document_get_from_notebook_child(GtkWidget *page)
  *
  *  @param page_num The notebook page number to search.
  *
- *  @return The corresponding document for the given notebook page, or @c NULL.
+ *  @return @transfer{none} The corresponding document for the given notebook page, or @c NULL.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_get_from_page(guint page_num)
@@ -385,7 +385,7 @@ GeanyDocument *document_get_from_page(guint page_num)
 /**
  *  Finds the current document.
  *
- *  @return A pointer to the current document or @c NULL if there are no opened documents.
+ *  @return @transfer{none} A pointer to the current document or @c NULL if there are no opened documents.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_get_current(void)
@@ -830,7 +830,7 @@ GeanyDocument *document_new_file_if_non_open(void)
  *  @param ft The filetype to set or @c NULL to detect it from @a filename if not @c NULL.
  *  @param text The initial content of the file (in UTF-8 encoding), or @c NULL.
  *
- *  @return The new document.
+ *  @return @transfer{none} The new document.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_new_file(const gchar *utf8_filename, GeanyFiletype *ft, const gchar *text)
@@ -914,7 +914,7 @@ GeanyDocument *document_new_file(const gchar *utf8_filename, GeanyFiletype *ft,
  *  @param ft The filetype for the document or @c NULL to auto-detect the filetype.
  *  @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
  *
- *  @return The document opened or @c NULL.
+ *  @return @transfer{none} The document opened or @c NULL.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_open_file(const gchar *locale_filename, gboolean readonly,
@@ -1558,7 +1558,7 @@ void document_open_file_list(const gchar *data, gsize length)
  *  Opens each file in the list @a filenames.
  *  Internally, document_open_file() is called for every list item.
  *
- *  @param filenames A list of filenames to load, in locale encoding.
+ *  @param filenames @elementtype{filename} A list of filenames to load, in locale encoding.
  *  @param readonly Whether to open the document in read-only mode.
  *  @param ft The filetype for the document or @c NULL to auto-detect the filetype.
  *  @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
@@ -3290,7 +3290,7 @@ const GdkColor *document_get_status_color(GeanyDocument *doc)
 /** Accessor function for @ref documents_array items.
  * @warning Always check the returned document is valid (@c doc->is_valid).
  * @param idx @c documents_array index.
- * @return The document, or @c NULL if @a idx is out of range.
+ * @return @transfer{none} The document, or @c NULL if @a idx is out of range.
  *
  *  @since 0.16
  */

src/editor.c

@@ -4871,7 +4871,7 @@ static ScintillaObject *create_new_sci(GeanyEditor *editor)
 
 /** Creates a new Scintilla @c GtkWidget based on the settings for @a editor.
  * @param editor Editor settings.
- * @return The new widget.
+ * @return @transfer{floating} The new widget.
  *
  * @since 0.15
  **/

src/editor.h

@@ -50,6 +50,8 @@ typedef enum
 }
 GeanyIndentType;
 
+/** @addtogir
+ * Auto indentation modes */
 typedef enum
 {
 	GEANY_AUTOINDENT_NONE = 0,

src/filetypes.c

@@ -55,7 +55,14 @@
 
 #define GEANY_FILETYPE_SEARCH_LINES 2 /* lines of file to search for filetype */
 
-GPtrArray *filetypes_array = NULL;	/* Dynamic array of filetype pointers */
+/** Dynamic array of filetype pointers
+ *
+ * List the list is dynamically expanded for custom filetypes filetypes so don't expect
+ * the list of known filetypes to be a constant.
+ *
+ * @elementtype{GeanyFiletype}
+ * */
+GPtrArray *filetypes_array = NULL;
 
 static GHashTable *filetypes_hash = NULL;	/* Hash of filetype pointers based on name keys */
 
@@ -233,7 +240,7 @@ static gint cmp_filetype(gconstpointer pft1, gconstpointer pft2, gpointer data)
 
 /** Gets a list of filetype pointers sorted by name.
  * The list does not change on subsequent calls.
- * @return The list - do not free.
+ * @return @elementtype{GeanyFiletype} @transfer{none} The list - do not free.
  * @see filetypes_by_title. */
 GEANY_API_SYMBOL
 const GSList *filetypes_get_sorted_by_name(void)
@@ -764,8 +771,8 @@ GeanyFiletype *filetypes_detect_from_document(GeanyDocument *doc)
  *
  *  @param utf8_filename The filename in UTF-8 encoding.
  *
- *  @return The detected filetype for @a utf8_filename or @c filetypes[GEANY_FILETYPES_NONE]
- *          if it could not be detected.
+ *  @return @transfer{none} The detected filetype for @a utf8_filename or
+ *           @c filetypes[GEANY_FILETYPES_NONE] if it could not be detected.
  **/
 GEANY_API_SYMBOL
 GeanyFiletype *filetypes_detect_from_file(const gchar *utf8_filename)
@@ -1246,7 +1253,7 @@ gboolean filetype_has_tags(GeanyFiletype *ft)
 
 /** Finds a filetype pointer from its @a name field.
  * @param name Filetype name.
- * @return The filetype found, or @c NULL.
+ * @return @transfer{none} The filetype found, or @c NULL.
  *
  * @since 0.15
  **/
@@ -1492,7 +1499,7 @@ void filetypes_reload_extensions(void)
 /** Accessor function for @ref GeanyData::filetypes_array items.
  * Example: @code ft = filetypes_index(GEANY_FILETYPES_C); @endcode
  * @param idx @c filetypes_array index.
- * @return The filetype, or @c NULL if @a idx is out of range.
+ * @return @transfer{none} The filetype, or @c NULL if @a idx is out of range.
  *
  *  @since 0.16
  */

src/filetypes.h

@@ -113,6 +113,9 @@ GeanyFiletypeID;
 
 #define filetype_id GeanyFiletypeID /* compat define - should be removed in the future */
 
+/** Filetype categories
+ *
+ * These are used to provide submenus for each category in the GUI */
 typedef enum
 {
 	GEANY_FILETYPE_GROUP_NONE,

src/keybindings.c

@@ -133,7 +133,7 @@ GdkModifierType keybindings_get_modifiers(GdkModifierType mods)
 /** Looks up a keybinding item.
  * @param group Group.
  * @param key_id Keybinding index for the group.
- * @return The keybinding.
+ * @return @transfer{none} The keybinding.
  * @since 0.19. */
 GEANY_API_SYMBOL
 GeanyKeyBinding *keybindings_get_item(GeanyKeyGroup *group, gsize key_id)
@@ -216,11 +216,11 @@ 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 Optional widget to set an accelerator for, or @c NULL.
- * @param cb 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.
+ * @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 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 The keybinding - normally this is ignored.
+ * @return @transfer{none} The keybinding - normally this is ignored.
  *
  * @since 1.26 (API 226)
  * @see See plugin_set_key_group_full

src/plugindata.h

@@ -222,8 +222,8 @@ typedef struct GeanyData
 {
 	struct GeanyApp				*app;				/**< Geany application data fields */
 	struct GeanyMainWidgets		*main_widgets;		/**< Important widgets in the main window */
-	GPtrArray					*documents_array;	/**< See document.h#documents_array. */
-	GPtrArray					*filetypes_array;	/**< Dynamic array of GeanyFiletype pointers */
+	GPtrArray					*documents_array;	/**< See document.h#documents_array. @elementtype{GeanyDocument} */
+	GPtrArray					*filetypes_array;	/**< Dynamic array of GeanyFiletype pointers. @elementtype{GeanyFiletype} */
 	struct GeanyPrefs			*prefs;				/**< General settings */
 	struct GeanyInterfacePrefs	*interface_prefs;	/**< Interface settings */
 	struct GeanyToolbarPrefs	*toolbar_prefs;		/**< Toolbar settings */

src/pluginutils.c

@@ -128,7 +128,9 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
  *          object has been destroyed), and disconnect yourself or not as appropriate.
  * @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. */
+ *       @c g_signal_connect() is safe and has lower overhead.
+ * @skip
+ **/
 GEANY_API_SYMBOL
 void plugin_signal_connect(GeanyPlugin *plugin,
 		GObject *object, const gchar *signal_name, gboolean after,
@@ -241,6 +243,7 @@ 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)
@@ -261,6 +264,7 @@ 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,
@@ -281,6 +285,7 @@ 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)
@@ -296,7 +301,8 @@ guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data)
  * @param count Number of keybindings for the group.
  * @param callback Group callback, or @c NULL if you only want individual keybinding callbacks.
  * @return The plugin's keybinding group.
- * @since 0.19. */
+ * @since 0.19.
+ * @skip */
 GEANY_API_SYMBOL
 GeanyKeyGroup *plugin_set_key_group(GeanyPlugin *plugin,
 		const gchar *section_name, gsize count, GeanyKeyGroupCallback callback)
@@ -315,10 +321,10 @@ 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 New-style group callback, or @c NULL if you only want individual keybinding callbacks.
- * @param pdata Plugin specific data, passed to the group callback.
+ * @param cb @null 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 The plugin's keybinding group.
+ * @return @transfer{none} The plugin's keybinding group.
  *
  * @since 1.26 (API 226)
  * @see See keybindings_set_item

src/search.h

@@ -43,12 +43,15 @@ typedef enum GeanyFindFlags
 }
 GeanyFindFlags;
 
-enum GeanyFindSelOptions
+/** @addtogir
+ * Find selection options */
+typedef enum
 {
 	GEANY_FIND_SEL_CURRENT_WORD,
 	GEANY_FIND_SEL_X,
 	GEANY_FIND_SEL_AGAIN
-};
+}
+GeanyFindSelOptions;
 
 /** Search preferences */
 typedef struct GeanySearchPrefs
@@ -58,7 +61,7 @@ typedef struct GeanySearchPrefs
 	gboolean	use_current_file_dir;	/* find in files directory to use on showing dialog */
 	gboolean	hide_find_dialog;		/* hide the find dialog on next or previous */
 	gboolean	replace_and_find_by_default;	/* enter in replace window performs Replace & Find instead of Replace */
-	enum GeanyFindSelOptions find_selection_type;
+	GeanyFindSelOptions find_selection_type;
 }
 GeanySearchPrefs;
 

src/spawn.c

@@ -999,6 +999,7 @@ 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/stash.c

@@ -359,7 +359,7 @@ static void free_stash_pref(StashPref *pref)
 
 /** Creates a new group.
  * @param name Name used for @c GKeyFile group.
- * @return Group. */
+ * @return @transfer{full} Group. */
 GEANY_API_SYMBOL
 StashGroup *stash_group_new(const gchar *name)
 {