Branch: refs/heads/master Author: Thomas Martitz kugel@rockbox.org Committer: Thomas Martitz kugel@rockbox.org Date: Thu, 17 Dec 2015 08:52:52 UTC Commit: 302b40e9778ff49407902f3ef9f272ed202f4547 https://github.com/geany/geany/commit/302b40e9778ff49407902f3ef9f272ed202f45...
Log Message: ----------- doxygen: various doxygen-related fixes in preparation for gtkdoc generation
Major changes are:
- Some types were accidentally documented, even though they couldn't be accessed by any exported API functions. Those are removed (especially from encodings.h).
- Some types were not documented where they should. Documentation is added for them. Members are not necessarily documented separately if names are self-explanatory.
- @a XXX refers to parameters of the function, it's inappropriate for highlighting NULL (change to @c)
- As per consensus, build_info is removed from GeanyData (replaced by pointer to avoid ABI break; added grep-able abi-todo tag so it doesn't get forgotten)
Modified Paths: -------------- doc/pluginsymbols.c src/build.c src/build.h src/editor.c src/editor.h src/encodings.h src/filetypes.h src/keybindings.c src/plugindata.h src/plugins.c src/search.h src/utils.c
Modified: doc/pluginsymbols.c 14 lines changed, 8 insertions(+), 6 deletions(-) =================================================================== @@ -37,8 +37,10 @@ */
/** Use the PLUGIN_VERSION_CHECK() macro instead. Required by Geany. - * @return . */ -gint plugin_version_check(gint); + * + * @param abi ABI version Geany was compiled with + * @return The API version the plugin was compiled with, or -1 if the plugin is incompatible. */ +gint plugin_version_check(gint abi);
/** Use the PLUGIN_SET_INFO() macro to define it. Required by Geany. * This function is called before the plugin is initialized, so Geany @@ -46,8 +48,8 @@ gint plugin_version_check(gint); * @param info The data struct which should be initialized by this function. */ void plugin_set_info(PluginInfo *info);
-/** @deprecated Use @ref GeanyPlugin.info instead. - * Basic information about a plugin, which is set in plugin_set_info(). */ +/** Basic information about a plugin, which is set in plugin_set_info(). + * @deprecated Use @ref GeanyPlugin.info instead.*/ const PluginInfo *plugin_info;
/** Basic information for the plugin and identification. */ @@ -64,8 +66,8 @@ const GeanyData *geany_data; * This is equivalent of @c geany_functions->p_document->document_new_file(NULL, NULL, NULL); */ const GeanyFunctions *geany_functions;
-/** @deprecated Use @ref ui_add_document_sensitive() instead. - * Plugin owned fields, including flags. */ +/** Plugin owned fields, including flags. + * @deprecated Use @ref ui_add_document_sensitive() instead.*/ PluginFields *plugin_fields;
/** An array for connecting GeanyObject events, which should be terminated with
Modified: src/build.c 4 lines changed, 2 insertions(+), 2 deletions(-) =================================================================== @@ -524,7 +524,7 @@ void build_remove_menu_item(const GeanyBuildSource src, const GeanyBuildGroup gr * @param grp the group of the specified menu item. * @param cmd the index of the command within the group. * - * @return a pointer to the @a GeanyBuildCommand structure or @a NULL if it doesn't exist. + * @return a pointer to the @a GeanyBuildCommand structure or @c NULL if it doesn't exist. * This is a pointer to an internal structure and must not be freed. * * @see build_menu_update @@ -553,7 +553,7 @@ GeanyBuildCommand *build_get_menu_item(GeanyBuildSource src, GeanyBuildGroup grp * @param cmd the index of the command within the group. * @param fld the field to return * - * @return a pointer to the constant string or @a NULL if it doesn't exist. + * @return a pointer to the constant string or @c NULL if it doesn't exist. * This is a pointer to an internal structure and must not be freed. * **/
Modified: src/build.h 30 lines changed, 15 insertions(+), 15 deletions(-) =================================================================== @@ -34,31 +34,31 @@ G_BEGIN_DECLS /** Groups of Build menu items. */ typedef enum { - GEANY_GBG_FT, /* *< filetype items */ - GEANY_GBG_NON_FT, /* *< non filetype items.*/ - GEANY_GBG_EXEC, /* *< execute items */ - GEANY_GBG_COUNT /* *< count of groups. */ + GEANY_GBG_FT, /**< filetype items */ + GEANY_GBG_NON_FT, /**< non filetype items.*/ + GEANY_GBG_EXEC, /**< execute items */ + GEANY_GBG_COUNT /**< count of groups. */ } GeanyBuildGroup;
/** Build menu item sources in increasing priority */ typedef enum { - GEANY_BCS_DEF, /* *< Default values. */ - GEANY_BCS_FT, /* *< System filetype values. */ - GEANY_BCS_HOME_FT, /* *< Filetypes in ~/.config/geany/filedefs */ - GEANY_BCS_PREF, /* *< Preferences file ~/.config/geany/geany.conf */ - GEANY_BCS_PROJ_FT, /* *< Project file filetype command */ - GEANY_BCS_PROJ, /* *< Project file if open. */ - GEANY_BCS_COUNT /* *< Count of sources. */ + GEANY_BCS_DEF, /**< Default values. */ + GEANY_BCS_FT, /**< System filetype values. */ + GEANY_BCS_HOME_FT, /**< Filetypes in ~/.config/geany/filedefs */ + GEANY_BCS_PREF, /**< Preferences file ~/.config/geany/geany.conf */ + GEANY_BCS_PROJ_FT, /**< Project file filetype command */ + GEANY_BCS_PROJ, /**< Project file if open. */ + GEANY_BCS_COUNT /**< Count of sources. */ } GeanyBuildSource;
/** The entries of a command for a menu item */ typedef enum GeanyBuildCmdEntries { - GEANY_BC_LABEL, /* *< The menu item label, _ marks mnemonic */ - GEANY_BC_COMMAND, /* *< The command to run. */ - GEANY_BC_WORKING_DIR, /* *< The directory to run in */ - GEANY_BC_CMDENTRIES_COUNT /* *< Count of entries */ + GEANY_BC_LABEL, /**< The menu item label, _ marks mnemonic */ + GEANY_BC_COMMAND, /**< The command to run. */ + GEANY_BC_WORKING_DIR, /**< The directory to run in */ + GEANY_BC_CMDENTRIES_COUNT /**< Count of entries */ } GeanyBuildCmdEntries;
void build_activate_menu_item(const GeanyBuildGroup grp, const guint cmd);
Modified: src/editor.c 2 lines changed, 1 insertions(+), 1 deletions(-) =================================================================== @@ -1783,7 +1783,7 @@ static gint find_start_bracket(ScintillaObject *sci, gint pos) }
-static gboolean append_calltip(GString *str, const TMTag *tag, filetype_id ft_id) +static gboolean append_calltip(GString *str, const TMTag *tag, GeanyFiletypeID ft_id) { if (! tag->arglist) return FALSE;
Modified: src/editor.h 9 lines changed, 5 insertions(+), 4 deletions(-) =================================================================== @@ -50,12 +50,13 @@ typedef enum } GeanyIndentType;
+/** Modes for automatic indentation */ typedef enum { - GEANY_AUTOINDENT_NONE = 0, - GEANY_AUTOINDENT_BASIC, - GEANY_AUTOINDENT_CURRENTCHARS, - GEANY_AUTOINDENT_MATCHBRACES + GEANY_AUTOINDENT_NONE = 0, /**< Autoindent Disabled */ + GEANY_AUTOINDENT_BASIC, /**< Very basic mode */ + GEANY_AUTOINDENT_CURRENTCHARS, /**< Autoindent based on the first char of the previous line */ + GEANY_AUTOINDENT_MATCHBRACES /**< Autoindent based on the position of the opening brace */ } GeanyAutoIndent;
Modified: src/encodings.h 5 lines changed, 1 insertions(+), 4 deletions(-) =================================================================== @@ -46,10 +46,7 @@ G_BEGIN_DECLS * Copyright (C) 2002 Red Hat, Inc. */
-/** - * @enum GeanyEncodingIndex - * List of known and supported encodings. - **/ +/** List of known and supported encodings. */ typedef enum { GEANY_ENCODING_ISO_8859_1,
Modified: src/filetypes.h 20 lines changed, 14 insertions(+), 6 deletions(-) =================================================================== @@ -38,7 +38,10 @@ G_BEGIN_DECLS /* Forward-declared to avoid including document.h since it includes this header */ struct GeanyDocument;
-/* Do not change the order, only append. */ +/** IDs of known filetypes + * + * @ref filetypes_array will contain an item for each. Use filetypes_array->len to + * determine the number of known filetypes at runtime */ typedef enum { GEANY_FILETYPES_NONE = 0, /* first filetype is always None & must be 0 */ @@ -106,8 +109,13 @@ typedef enum /* ^ append items here */ GEANY_MAX_BUILT_IN_FILETYPES /* Don't use this, use filetypes_array->len instead */ } -filetype_id; +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, @@ -128,7 +136,7 @@ GeanyFiletypeGroupID; /** Represents a filetype. */ typedef struct GeanyFiletype { - filetype_id id; /**< Index in @c filetypes_array. */ + GeanyFiletypeID id; /**< Index in @c filetypes_array. */ /** Represents the langType of tagmanager (see the table * in tagmanager/parsers.h), -1 represents all, -2 none. */ langType lang; @@ -158,9 +166,7 @@ typedef struct GeanyFiletype } GeanyFiletype;
-extern GPtrArray *filetypes_array; - -/** Wraps filetypes_array so it can be used with C array syntax. +/** Wraps @ref filetypes_array so it can be used with C array syntax. * Example: filetypes[GEANY_FILETYPES_C]->name = ...; * @see filetypes_index(). */ #define filetypes ((GeanyFiletype **)GEANY(filetypes_array)->pdata) @@ -179,6 +185,8 @@ const GSList *filetypes_get_sorted_by_name(void);
#ifdef GEANY_PRIVATE
+extern GPtrArray *filetypes_array; + extern GSList *filetypes_by_title;
Modified: src/keybindings.c 4 lines changed, 2 insertions(+), 2 deletions(-) =================================================================== @@ -158,7 +158,7 @@ GeanyKeyBinding *keybindings_get_item(GeanyKeyGroup *group, gsize key_id) * @param key_id Keybinding index for the group. * @param callback Function to call when activated, or @c NULL to use the group callback. * Usually it's better to use the group callback instead - see plugin_set_key_group(). - * @param key (Lower case) default key, e.g. @c GDK_j, but usually 0 for unset. + * @param key Default key, e.g. @c GDK_j (must be lower case), but usually 0 for unset. * @param mod Default modifier, e.g. @c GDK_CONTROL_MASK, but usually 0 for unset. * @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 @@ -211,7 +211,7 @@ GeanyKeyBinding *keybindings_set_item(GeanyKeyGroup *group, gsize key_id, * * @param group Group. * @param key_id Keybinding index for the group. - * @param key (Lower case) default key, e.g. @c GDK_j, but usually 0 for unset. + * @param key Default key, e.g. @c GDK_j (must be lower case), but usually 0 for unset. * @param mod Default modifier, e.g. @c GDK_CONTROL_MASK, but usually 0 for unset. * @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
Modified: src/plugindata.h 2 lines changed, 1 insertions(+), 1 deletions(-) =================================================================== @@ -232,7 +232,7 @@ typedef struct GeanyData struct GeanySearchPrefs *search_prefs; /**< Search-related settings */ struct GeanyToolPrefs *tool_prefs; /**< Tool settings */ struct GeanyTemplatePrefs *template_prefs; /**< Template settings */ - struct GeanyBuildInfo *build_info; /**< Current build information */ + gpointer *_compat; /* Remove field on next ABI break (abi-todo) */ GSList *filetypes_by_title; /**< See filetypes.h#filetypes_by_title. */ } GeanyData;
Modified: src/plugins.c 2 lines changed, 1 insertions(+), 1 deletions(-) =================================================================== @@ -119,7 +119,7 @@ geany_data_init(void) &search_prefs, &tool_prefs, &template_prefs, - &build_info, + NULL, /* Remove field on next ABI break (abi-todo) */ filetypes_by_title };
Modified: src/search.h 2 lines changed, 1 insertions(+), 1 deletions(-) =================================================================== @@ -54,7 +54,7 @@ enum GeanyFindSelOptions typedef struct GeanySearchPrefs { gboolean always_wrap; /* don't ask whether to wrap search */ - gboolean use_current_word; /**< Use current word for default search text */ + gboolean use_current_word; /* Use current word for default search text */ 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 */
Modified: src/utils.c 20 lines changed, 10 insertions(+), 10 deletions(-) =================================================================== @@ -1647,16 +1647,16 @@ const gchar *utils_get_default_dir_utf8(void) /** * Wraps @c spawn_sync(), which see. * - * @param dir The child's current working directory, or @a NULL to inherit parent's. + * @param dir The child's current working directory, or @c NULL to inherit parent's. * @param argv The child's argument vector. - * @param env The child's environment, or @a NULL to inherit parent's. + * @param env The child's environment, or @c NULL to inherit parent's. * @param flags Ignored. * @param child_setup Ignored. * @param user_data Ignored. - * @param std_out The return location for child output, or @a NULL. - * @param std_err The return location for child error messages, or @a NULL. - * @param exit_status The child exit status, as returned by waitpid(), or @a NULL. - * @param error The return location for error or @a NULL. + * @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. + * @param exit_status The child exit status, as returned by waitpid(), or @c NULL. + * @param error The return location for error or @c NULL. * * @return @c TRUE on success, @c FALSE if an error was set. **/ @@ -1682,14 +1682,14 @@ gboolean utils_spawn_sync(const gchar *dir, gchar **argv, gchar **env, GSpawnFla /** * Wraps @c spawn_async(), which see. * - * @param dir The child's current working directory, or @a NULL to inherit parent's. + * @param dir The child's current working directory, or @c NULL to inherit parent's. * @param argv The child's argument vector. - * @param env The child's environment, or @a NULL to inherit parent's. + * @param env The child's environment, or @c NULL to inherit parent's. * @param flags Ignored. * @param child_setup 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 @a NULL. + * @param error The return location for error or @c NULL. * * @return @c TRUE on success, @c FALSE if an error was set. **/ @@ -1959,7 +1959,7 @@ static gboolean str_in_array(const gchar **haystack, const gchar *needle) * @param first_varname Name of the first variable to copy into the new array. * @param ... Key-value pairs of variable names and values, @c NULL-terminated. * - * @return The new environment array. + * @return The new environment array. Use @c g_strfreev() to free it. **/ GEANY_API_SYMBOL gchar **utils_copy_environment(const gchar **exclude_vars, const gchar *first_varname, ...)
-------------- This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).