Merge pull request #826 from kugel-/doxygen-fixes2

Doxygen API fixes and cleanup.

doc/pluginsymbols.c

@@ -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

src/Makefile.am

@@ -5,6 +5,7 @@ EXTRA_DIST = \
 	gb.c \
 	plugindata.h \
 	documentprivate.h \
+	encodingsprivate.h \
 	filetypesprivate.h \
 	keybindingsprivate.h \
 	pluginprivate.h \

src/build.c

@@ -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.
  *
  **/

src/build.h

@@ -34,31 +34,31 @@ G_BEGIN_DECLS
 /** Groups of Build menu items. */
 typedef enum
 {
-	GEANY_GBG_FT,		/* *< filetype items */
+	GEANY_GBG_FT,		/**< filetype items */
-	GEANY_GBG_NON_FT,	/* *< non filetype items.*/
+	GEANY_GBG_NON_FT,	/**< non filetype items.*/
-	GEANY_GBG_EXEC,		/* *< execute items */
+	GEANY_GBG_EXEC,		/**< execute items */
-	GEANY_GBG_COUNT		/* *< count of groups. */
+	GEANY_GBG_COUNT		/**< count of groups. */
 } GeanyBuildGroup;
 
 /** Build menu item sources in increasing priority */
 typedef enum
 {
-	GEANY_BCS_DEF,		/* *< Default values. */
+	GEANY_BCS_DEF,		/**< Default values. */
-	GEANY_BCS_FT,		/* *< System filetype values. */
+	GEANY_BCS_FT,		/**< System filetype values. */
-	GEANY_BCS_HOME_FT,	/* *< Filetypes in ~/.config/geany/filedefs */
+	GEANY_BCS_HOME_FT,	/**< Filetypes in ~/.config/geany/filedefs */
-	GEANY_BCS_PREF,		/* *< Preferences file ~/.config/geany/geany.conf */
+	GEANY_BCS_PREF,		/**< Preferences file ~/.config/geany/geany.conf */
-	GEANY_BCS_PROJ_FT,	/* *< Project file filetype command */
+	GEANY_BCS_PROJ_FT,	/**< Project file filetype command */
-	GEANY_BCS_PROJ,		/* *< Project file if open. */
+	GEANY_BCS_PROJ,		/**< Project file if open. */
-	GEANY_BCS_COUNT		/* *< Count of sources. */
+	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_LABEL,				/**< The menu item label, _ marks mnemonic */
-	GEANY_BC_COMMAND,			/* *< The command to run. */
+	GEANY_BC_COMMAND,			/**< The command to run. */
-	GEANY_BC_WORKING_DIR,		/* *< The directory to run in */
+	GEANY_BC_WORKING_DIR,		/**< The directory to run in */
-	GEANY_BC_CMDENTRIES_COUNT	/* *< Count of entries */
+	GEANY_BC_CMDENTRIES_COUNT	/**< Count of entries */
 } GeanyBuildCmdEntries;
 
 void build_activate_menu_item(const GeanyBuildGroup grp, const guint cmd);

src/dialogs.c

@@ -33,6 +33,7 @@
 #include "build.h"
 #include "document.h"
 #include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypes.h"
 #include "main.h"
 #include "support.h"

src/document.c

@@ -35,6 +35,7 @@
 #include "dialogs.h"
 #include "documentprivate.h"
 #include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypesprivate.h"
 #include "geany.h" /* FIXME: why is this needed for DOC_FILENAME()? should come from documentprivate.h/document.h */
 #include "geanyobject.h"

src/editor.c

@@ -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;

src/encodings.c

@@ -35,6 +35,7 @@
 #endif
 
 #include "encodings.h"
+#include "encodingsprivate.h"
 
 #include "app.h"
 #include "callbacks.h"

src/encodings.h

@@ -40,29 +40,13 @@
 
 G_BEGIN_DECLS
 
-typedef enum
-{
-	NONE = 0,
-	WESTEUROPEAN,
-	EASTEUROPEAN,
-	EASTASIAN,
-	ASIAN,
-	MIDDLEEASTERN,
-	UNICODE,
-
-	GEANY_ENCODING_GROUPS_MAX
-} GeanyEncodingGroup;
-
 /*
  * The original versions of the following tables are taken from profterm
  *
  * Copyright (C) 2002 Red Hat, Inc.
  */
 
-/**
+/** List of known and supported encodings. */
- * @enum GeanyEncodingIndex
- * List of known and supported encodings.
- **/
 typedef enum
 {
 	GEANY_ENCODING_ISO_8859_1,
@@ -139,23 +123,8 @@ typedef enum
 	GEANY_ENCODING_CP_932,
 
 	GEANY_ENCODINGS_MAX
-} GeanyEncodingIndex;
+}
-
+GeanyEncodingIndex;
-/** Structure to represent an encoding to be used in Geany. */
-typedef struct
-{
-	/** The index of the encoding, must be one of GeanyEncodingIndex. */
-	gint   				 idx;
-	/** Internally used member for grouping */
-	gint   				 order;
-	/** Internally used member for grouping */
-	GeanyEncodingGroup   group;
-	/** String representation of the encoding, e.g. "ISO-8859-3" */
-	const gchar			*charset;
-	/** Translatable and descriptive name of the encoding, e.g. "South European" */
-	const gchar			*name;
-} GeanyEncoding;
-
 
 gchar *encodings_convert_to_utf8(const gchar *buffer, gssize size, gchar **used_encoding);
 
@@ -166,44 +135,6 @@ gchar *encodings_convert_to_utf8_from_charset(const gchar *buffer, gssize size,
 
 const gchar* encodings_get_charset_from_index(gint idx);
 
-
-#ifdef GEANY_PRIVATE
-
-const GeanyEncoding* encodings_get_from_charset(const gchar *charset);
-const GeanyEncoding* encodings_get_from_index(gint idx);
-
-gchar* encodings_to_string(const GeanyEncoding* enc);
-const gchar* encodings_get_charset(const GeanyEncoding* enc);
-
-void encodings_select_radio_item(const gchar *charset);
-
-void encodings_init(void);
-void encodings_finalize(void);
-
-GtkTreeStore *encodings_encoding_store_new(gboolean has_detect);
-
-gint encodings_encoding_store_get_encoding(GtkTreeStore *store, GtkTreeIter *iter);
-
-gboolean encodings_encoding_store_get_iter(GtkTreeStore *store, GtkTreeIter *iter, gint enc);
-
-void encodings_encoding_store_cell_data_func(GtkCellLayout *cell_layout, GtkCellRenderer *cell,
-		GtkTreeModel *tree_model, GtkTreeIter *iter, gpointer data);
-
-gboolean encodings_is_unicode_charset(const gchar *string);
-
-gboolean encodings_convert_to_utf8_auto(gchar **buf, gsize *size, const gchar *forced_enc,
-		gchar **used_encoding, gboolean *has_bom, gboolean *partial);
-
-
-extern GeanyEncoding encodings[GEANY_ENCODINGS_MAX];
-
-
-GeanyEncodingIndex encodings_scan_unicode_bom(const gchar *string, gsize len, guint *bom_len);
-
-GeanyEncodingIndex encodings_get_idx_from_charset(const gchar *charset);
-
-#endif /* GEANY_PRIVATE */
-
 G_END_DECLS
 
 #endif /* GEANY_ENCODINGS_H */

src/encodingsprivate.h

@@ -0,0 +1,84 @@
+/*
+ *      encodingsprivate.h - this file is part of Geany, a fast and lightweight IDE
+ *
+ *      Copyright 2005-2012 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
+ *      Copyright 2006-2012 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
+ *
+ *      This program is free software; you can redistribute it and/or modify
+ *      it under the terms of the GNU General Public License as published by
+ *      the Free Software Foundation; either version 2 of the License, or
+ *      (at your option) any later version.
+ *
+ *      This program is distributed in the hope that it will be useful,
+ *      but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *      GNU General Public License for more details.
+ *
+ *      You should have received a copy of the GNU General Public License along
+ *      with this program; if not, write to the Free Software Foundation, Inc.,
+ *      51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef ENCODINGSPRIVATE_H
+#define ENCODINGSPRIVATE_H
+
+#include "encodings.h"
+
+/* Groups of encodings */
+typedef enum
+{
+	NONE = 0,
+	WESTEUROPEAN,
+	EASTEUROPEAN,
+	EASTASIAN,
+	ASIAN,
+	MIDDLEEASTERN,
+	UNICODE,
+
+	GEANY_ENCODING_GROUPS_MAX
+}
+GeanyEncodingGroup;
+
+/* Structure to represent an encoding to be used in Geany. */
+typedef struct GeanyEncoding
+{
+	GeanyEncodingIndex      idx; /* The index of the encoding inside globa encodes array.*/
+	gint                    order; /* Internally used member for grouping */
+	GeanyEncodingGroup      group; /* Internally used member for grouping */
+	const gchar            *charset; /* String representation of the encoding, e.g. "ISO-8859-3" */
+	const gchar            *name; /* Translatable and descriptive name of the encoding, e.g. "South European" */
+}
+GeanyEncoding;
+
+const GeanyEncoding* encodings_get_from_charset(const gchar *charset);
+const GeanyEncoding* encodings_get_from_index(gint idx);
+
+gchar* encodings_to_string(const GeanyEncoding* enc);
+const gchar* encodings_get_charset(const GeanyEncoding* enc);
+
+void encodings_select_radio_item(const gchar *charset);
+
+void encodings_init(void);
+void encodings_finalize(void);
+
+GtkTreeStore *encodings_encoding_store_new(gboolean has_detect);
+
+gint encodings_encoding_store_get_encoding(GtkTreeStore *store, GtkTreeIter *iter);
+
+gboolean encodings_encoding_store_get_iter(GtkTreeStore *store, GtkTreeIter *iter, gint enc);
+
+void encodings_encoding_store_cell_data_func(GtkCellLayout *cell_layout, GtkCellRenderer *cell,
+                                             GtkTreeModel *tree_model, GtkTreeIter *iter, gpointer data);
+
+gboolean encodings_is_unicode_charset(const gchar *string);
+
+gboolean encodings_convert_to_utf8_auto(gchar **buf, gsize *size, const gchar *forced_enc,
+                                        gchar **used_encoding, gboolean *has_bom, gboolean *partial);
+
+GeanyEncodingIndex encodings_scan_unicode_bom(const gchar *string, gsize len, guint *bom_len);
+
+GeanyEncodingIndex encodings_get_idx_from_charset(const gchar *charset);
+
+extern GeanyEncoding encodings[GEANY_ENCODINGS_MAX];
+
+#endif /* ENCODINGSPRIVATE_H */

src/filetypes.h

@@ -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 will contain an item for each. Use GeanyData::filetypes_array to
+ * determine the known filetypes at runtime */
 typedef enum
 {
 	GEANY_FILETYPES_NONE = 0,	/* first filetype is always None & must be 0 */
@@ -106,7 +109,9 @@ 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 */
 
 typedef enum
 {
@@ -128,7 +133,7 @@ GeanyFiletypeGroupID;
 /** Represents a filetype. */
 typedef struct GeanyFiletype
 {
-	filetype_id		  id;				/**< Index in @c filetypes_array. */
+	GeanyFiletypeID	  id;				/**< Index in @ref filetypes. */
 	/** Represents the langType of tagmanager (see the table
 	 * in tagmanager/parsers.h), -1 represents all, -2 none. */
 	langType 		  lang;
@@ -158,9 +163,7 @@ typedef struct GeanyFiletype
 }
 GeanyFiletype;
 
-extern GPtrArray *filetypes_array;
+/** Wraps @ref GeanyData::filetypes_array so it can be used with C array syntax.
-
-/** Wraps 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 +182,8 @@ const GSList *filetypes_get_sorted_by_name(void);
 
 #ifdef GEANY_PRIVATE
 
+extern GPtrArray *filetypes_array;
+
 extern GSList *filetypes_by_title;
 
 

src/keybindings.c

@@ -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

src/keybindings.h

@@ -55,7 +55,7 @@ typedef gboolean (*GeanyKeyGroupCallback) (guint key_id);
  * with the same key combination to handle it).
  *
  * @since 1.26 (API 226) */
-typedef gboolean (*GeanyKeyGroupFunc)(GeanyKeyGroup *group, guint key_id, gpointer pdata);
+typedef gboolean (*GeanyKeyGroupFunc)(GeanyKeyGroup *group, guint key_id, gpointer user_data);
 
 /** Function pointer type used for keybinding callbacks. */
 typedef void (*GeanyKeyCallback) (guint key_id);
@@ -67,7 +67,7 @@ typedef void (*GeanyKeyCallback) (guint key_id);
  * with the same key combination to handle it).
  *
  * @since 1.26 (API 226) */
-typedef gboolean (*GeanyKeyBindingFunc)(GeanyKeyBinding *key, guint key_id, gpointer pdata);
+typedef gboolean (*GeanyKeyBindingFunc)(GeanyKeyBinding *key, guint key_id, gpointer user_data);
 
 /** Represents a single keybinding action.
  *

src/keyfile.c

@@ -38,6 +38,7 @@
 #include "build.h"
 #include "document.h"
 #include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypes.h"
 #include "geanyobject.h"
 #include "main.h"

src/libmain.c

@@ -36,7 +36,7 @@
 #include "callbacks.h"
 #include "dialogs.h"
 #include "document.h"
-#include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypes.h"
 #include "geanyobject.h"
 #include "highlighting.h"

src/plugindata.h

@@ -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;

src/plugins.c

@@ -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
 	};
 

src/prefs.c

@@ -39,7 +39,7 @@
 #include "dialogs.h"
 #include "documentprivate.h"
 #include "editor.h"
-#include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypes.h"
 #include "geanywraplabel.h"
 #include "keybindingsprivate.h"

src/search.c

@@ -33,6 +33,7 @@
 #include "app.h"
 #include "document.h"
 #include "encodings.h"
+#include "encodingsprivate.h"
 #include "keyfile.h"
 #include "msgwindow.h"
 #include "prefs.h"

src/templates.c

@@ -32,7 +32,7 @@
 
 #include "app.h"
 #include "document.h"
-#include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypes.h"
 #include "geany.h"
 #include "geanymenubuttonaction.h"

src/ui_utils.c

@@ -34,7 +34,7 @@
 #include "callbacks.h"
 #include "dialogs.h"
 #include "documentprivate.h"
-#include "encodings.h"
+#include "encodingsprivate.h"
 #include "filetypes.h"
 #include "geanymenubuttonaction.h"
 #include "keyfile.h"

src/utils.c

@@ -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_out The return location for child output, or @c NULL.
- *  @param std_err The return location for child error messages, or @a 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 @a NULL.
+ *  @param exit_status The child exit status, as returned by waitpid(), or @c 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.
  **/
@@ -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, ...)