[geany/geany] 302b40: doxygen: various doxygen-related fixes in preparation for gtkdoc generation
Thomas Martitz
git-noreply at xxxxx
Mon Jan 18 02:47:06 UTC 2016
Branch: refs/heads/master
Author: Thomas Martitz <kugel at rockbox.org>
Committer: Thomas Martitz <kugel at rockbox.org>
Date: Thu, 17 Dec 2015 08:52:52 UTC
Commit: 302b40e9778ff49407902f3ef9f272ed202f4547
https://github.com/geany/geany/commit/302b40e9778ff49407902f3ef9f272ed202f4547
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).
More information about the Commits
mailing list