Revision: 1284 http://geany-plugins.svn.sourceforge.net/geany-plugins/?rev=1284&view=re... Author: colombanw Date: 2010-04-22 15:07:18 +0000 (Thu, 22 Apr 2010)

Log Message: ----------- GeanyGenDoc: Add some code documentation

Modified Paths: -------------- trunk/geanygendoc/src/ggd-doc-setting.c trunk/geanygendoc/src/ggd-doc-setting.h trunk/geanygendoc/src/ggd-file-type-loader.c trunk/geanygendoc/src/ggd-file-type-loader.h trunk/geanygendoc/src/ggd-file-type-manager.c trunk/geanygendoc/src/ggd-file-type.c trunk/geanygendoc/src/ggd-options.c trunk/geanygendoc/src/ggd-options.h trunk/geanygendoc/src/ggd-tag-utils.c trunk/geanygendoc/src/ggd-tag-utils.h trunk/geanygendoc/src/ggd-utils.c trunk/geanygendoc/src/ggd-utils.h trunk/geanygendoc/src/ggd.c

Modified: trunk/geanygendoc/src/ggd-doc-setting.c =================================================================== --- trunk/geanygendoc/src/ggd-doc-setting.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-doc-setting.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -27,6 +27,15 @@ #include <geanyplugin.h>

+/** + * ggd_doc_setting_new: + * @match: A setting match pattern + * + * Creates a new #GgdDocSetting. + * + * Returns: The newly created #GgdDocSetting that should be unref'd with + * ggd_doc_setting_unref() when no longer needed. + */ GgdDocSetting * ggd_doc_setting_new (const gchar *match) { @@ -46,6 +55,14 @@ return setting; }

+/** + * ggd_doc_setting_ref: + * @setting: A #GgdDocSetting + * + * Adds a reference to a #GgdDocSetting. + * + * Returns: The setting. + */ GgdDocSetting * ggd_doc_setting_ref (GgdDocSetting *setting) { @@ -56,6 +73,13 @@ return setting; }

+/** + * ggd_doc_setting_unref: + * @setting: A #GgdDocSetting + * + * Drops a reference from a #GgdDocSetting. When its reference count drops to 0, + * the setting is destroyed. + */ void ggd_doc_setting_unref (GgdDocSetting *setting) { @@ -68,6 +92,14 @@ } }

+/** + * ggd_doc_setting_dump: + * @setting: A #GgdDocSetting + * @stream: A file stream to which write the dump + * + * Dumps a #GgdDocSetting in a human-readable form. This is mostly meant for + * debugging purposes. + */ void ggd_doc_setting_dump (const GgdDocSetting *setting, FILE *stream) @@ -114,7 +146,14 @@

-/* Gets a position from a string. returns -1 on error */ +/** + * ggd_position_from_string: + * @string: A string representing a #GgdPosition + * + * Translates a string to a #GgdPosition. + * + * Returns: The corresponding #GgdPosition, or -1 on error. + */ GgdPosition ggd_position_from_string (const gchar *string) { @@ -141,7 +180,14 @@ return -1; }

-/* Gets a policy from a string. returns -1 on error */ +/** + * ggd_policy_from_string: + * @string: A string representing a #GgdPolicy + * + * Translates a string to a #GgdPolicy. + * + * Returns: The corresponding #GgdPolicy, or -1 on error. + */ GgdPolicy ggd_policy_from_string (const gchar *string) { @@ -168,7 +214,14 @@ return -1; }

-/* Gets a merge policy from a string. returns -1 on error */ +/** + * ggd_merge_policy_from_string: + * @string: A string representing a merge policy + * + * Translates a string to a merge policy. + * + * Returns: The merge policy, or -1 on error. + */ gboolean ggd_merge_policy_from_string (const gchar *string) { @@ -193,3 +246,13 @@

return -1; } + +/** + * ggd_match_from_string: + * @name: A string representing a match + * + * Translates a string to a match. + * + * Returns: The match, or 0 on error. + */ +/* documents a define found in the header */

Modified: trunk/geanygendoc/src/ggd-doc-setting.h =================================================================== --- trunk/geanygendoc/src/ggd-doc-setting.h 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-doc-setting.h 2010-04-22 15:07:18 UTC (rev 1284) @@ -29,6 +29,14 @@ G_BEGIN_DECLS

+/** + * _GgdPosition: + * @GGD_POS_BEFORE: Place the documentation before what it documents + * @GGD_POS_AFTER: Place the documentation after what it documents + * @GGD_POS_CURSOR: Place the documentation at the cursor's position + * + * Possible positions for documentation insertion. + */ typedef enum _GgdPosition { GGD_POS_BEFORE, @@ -36,6 +44,13 @@ GGD_POS_CURSOR } GgdPosition;

+/** + * _GgdPolicy: + * @GGD_POLICY_KEEP: Document the symbol + * @GGD_POLICY_FORWARD: Forward the documentation request to the parent symbol + * + * Possible policies for documenting symbols. + */ typedef enum _GgdPolicy { GGD_POLICY_KEEP,

Modified: trunk/geanygendoc/src/ggd-file-type-loader.c =================================================================== --- trunk/geanygendoc/src/ggd-file-type-loader.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-file-type-loader.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -84,6 +84,7 @@ */

+/*< standard >*/ GQuark ggd_file_type_load_error_quark (void) {

Modified: trunk/geanygendoc/src/ggd-file-type-loader.h =================================================================== --- trunk/geanygendoc/src/ggd-file-type-loader.h 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-file-type-loader.h 2010-04-22 15:07:18 UTC (rev 1284) @@ -27,6 +27,14 @@ G_BEGIN_DECLS

+/** + * GgdConfError: + * @GGD_FILE_TYPE_LOAD_ERROR_READ: A read failed + * @GGD_FILE_TYPE_LOAD_ERROR_PARSE: Parsing of a part of the input failed + * @GGD_FILE_TYPE_LOAD_ERROR_FAILED: Something failed + * + * Error codes of the %GGD_FILE_TYPE_LOAD_ERROR domain. + */ typedef enum _GgdConfError { GGD_FILE_TYPE_LOAD_ERROR_READ, @@ -34,6 +42,7 @@ GGD_FILE_TYPE_LOAD_ERROR_FAILED } GgdConfError;

+/*< standard >*/ #define GGD_FILE_TYPE_LOAD_ERROR (ggd_file_type_load_error_quark ())

GQuark ggd_file_type_load_error_quark (void) G_GNUC_CONST;

Modified: trunk/geanygendoc/src/ggd-file-type-manager.c =================================================================== --- trunk/geanygendoc/src/ggd-file-type-manager.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-file-type-manager.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -30,10 +30,37 @@ #include "ggd-utils.h"

+/** + * SECTION: ggd-file-type-manager + * @include ggd-file-type-manager.h + * + * The file type manager. It manages a set of file type, caching them and + * loading them when needed. + * + * Use ggd_file_type_manager_init() to initialize the file type manager, and + * ggd_file_type_manager_uninit() to de-initialize it, releasing the resources + * allocated for it. A re-initialization can be done be de-initializing and the + * re-initializing the file type manager. This can be useful to e.g. flush the + * caches and the for reloading of file types. + * + * To get a file type from the file type manager, simply use + * ggd_file_type_manager_get_file_type(). If the requested file type must be + * loaded first, it will be done transparently. + */ + + +/* Hash table holding the loaded #GgdFileType<!-- -->s */ static GHashTable *GGD_ft_table = NULL;

+/* checks whether the file type manager is initialized */ #define ggd_file_type_manager_is_initialized() (GGD_ft_table != NULL)

+/** + * ggd_file_type_manager_init: + * + * Initializes the file type manager. This must be called before any other file + * type manager functions. + */ void ggd_file_type_manager_init (void) { @@ -44,6 +71,13 @@ (GDestroyNotify)ggd_file_type_unref); }

+/** + * ggd_file_type_manager_uninit: + * + * De-initializes the file type manager, releasing memory allocated by it. + * It may also be used to force reloading of file type descriptions: simply call + * it and then re-initialize it with ggd_file_type_manager_init(). + */ void ggd_file_type_manager_uninit (void) { @@ -53,6 +87,12 @@ GGD_ft_table = NULL; }

+/** + * ggd_file_type_manager_add_file_type: + * @filetype: A #GgdFileType + * + * Adds a file type to the file type manager. + */ void ggd_file_type_manager_add_file_type (GgdFileType *filetype) { @@ -64,6 +104,8 @@ ggd_file_type_ref (filetype)); }

+/* Same as ggd_file_type_manager_get_conf_path() but uses a #GeanyFiletype and + * doesn't do come safety checks. */ static gchar * ggd_file_type_manager_get_conf_path_intern (GeanyFiletype *geany_ft, GgdPerms prems_req, @@ -82,6 +124,18 @@ return filename; }

+/** + * ggd_file_type_manager_get_conf_path: + * @id: The ID of a #GeanyFiletype + * @prems_req: Required permissions on the file + * @error: Return location for errors, or %NULL to ignore them + * + * Gets the path to the configuration file of a file type from a given + * #GeanyFiletype ID. + * + * Returns: A newly allocated path to the requested configuration file that + * should be freed with g_free(), or %NULL on error. + */ gchar * ggd_file_type_manager_get_conf_path (filetype_id id, GgdPerms perms_req, @@ -93,6 +147,15 @@ error); }

+/** + * ggd_file_type_manager_load_file_type: + * @id: A #GeanyFiletype ID + * + * Loads the #GgdFileType corresponding to a Geany's file type. + * + * Returns: The loaded #GgdFileType, that should not be unref'd, or %NULL on + * failure. + */ GgdFileType * ggd_file_type_manager_load_file_type (filetype_id id) { @@ -130,6 +193,17 @@ return ft; }

+/** + * ggd_file_type_manager_get_file_type: + * @id: A #GeanyFiletype ID + * + * Gets a #GgdFileType from the file type manager by its Geany's file type ID. + * If the file type isn't already known, it will be transparently loaded. + * + * Returns: A #GgdFileType that shouldn't be unref'd, or %NULL if the requested + * file type neither can be found on the loaded file type nor can be + * loaded. + */ GgdFileType * ggd_file_type_manager_get_file_type (filetype_id id) { @@ -148,6 +222,16 @@ return ft; }

+/** + * ggd_file_type_manager_get_doc_type: + * @ft: A #GeanyFiletype ID + * @docname: The documentation type identifier + * + * Gets the #GgdDocType for a file type and a documentation type identifier. + * + * Returns: The #GgdDocType corresponding to the file and documentation type, + * or %NULL on failure. + */ GgdDocType * ggd_file_type_manager_get_doc_type (filetype_id ft, const gchar *docname)

Modified: trunk/geanygendoc/src/ggd-file-type.c =================================================================== --- trunk/geanygendoc/src/ggd-file-type.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-file-type.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -27,6 +27,25 @@ #include "ggd-doc-type.h"

+/** + * SECTION: ggd-file-type + * @include: ggd-file-type.h + * + * A #GgdFileType represents the rules for a language type. + * + * It uses GObject-style reference counting through ggd_file_type_ref() and + * ggd_file_type_unref(). + */ + + +/** + * ggd_file_type_new: + * @type: A #GeanyFiletype ID + * + * Creates a new #GgdFileType for a Geany's file type. + * + * Returns: A newly created #GgdFileType. + */ GgdFileType * ggd_file_type_new (filetype_id type) { @@ -43,6 +62,14 @@ return ft; }

+/** + * ggd_file_type_ref: + * @filetype: A #GgdFileType + * + * Adds a reference to a #GgdFileType. + * + * Returns: The filetype + */ GgdFileType * ggd_file_type_ref (GgdFileType *filetype) { @@ -53,6 +80,13 @@ return filetype; }

+/** + * ggd_file_type_unref: + * @filetype: A #GgdFileType + * + * Drops a reference from a #GgdFileType. When a file type's reference count + * drops to zero, the file type is destroyed. + */ void ggd_file_type_unref (GgdFileType *filetype) { @@ -68,6 +102,7 @@ } }

+/* function to call on each element of the doc type table in order to dump it */ static void dump_doctypes_hfunc (gpointer key G_GNUC_UNUSED, gpointer value, @@ -76,6 +111,13 @@ ggd_doc_type_dump (value, data); }

+/** + * ggd_file_type_dump: + * @filetype: A #GgdFileType + * @stream: A file stream to which write the dump + * + * A user-readable dump of a #GgdFileType, mostly for debugging purposes. + */ void ggd_file_type_dump (const GgdFileType *filetype, FILE *stream) @@ -93,6 +135,13 @@ g_hash_table_foreach (filetype->doctypes, dump_doctypes_hfunc, stream); }

+/** + * ggd_file_type_add_doc: + * @filetype: A #GgdFileType + * @doctype: A #GgdDocType + * + * Adds a #GgdDocType to a #GgdFileType. + */ void ggd_file_type_add_doc (GgdFileType *filetype, GgdDocType *doctype) @@ -105,6 +154,17 @@ } }

+/** + * ggd_file_type_get_doc: + * @filetype: A #GgdFileType + * @name: A documentation type identifier + * + * Gets the #GgdDocType of a #GgdFileType that corresponds to the given + * documentation type identifier. + * + * Returns: The #GgdDocType corresponding to @name that shouldn't be unref'd, or + * %NULL if not found in @filetype. + */ GgdDocType * ggd_file_type_get_doc (const GgdFileType *filetype, const gchar *name)

Modified: trunk/geanygendoc/src/ggd-options.c =================================================================== --- trunk/geanygendoc/src/ggd-options.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-options.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -28,6 +28,11 @@ #include <gtk/gtk.h>

+/* This module is strongly inspired from Geany's Stash module with some design + * changes and a complete reimplementation. + * The major difference is the way proxies are managed. */ + + /* stolen from Geany */ #define foreach_array(array, type, item) \ for ((item) = ((type*)(gpointer)(array)->data); \ @@ -35,6 +40,20 @@ (item)++)

+/* + * GgdOptEntry: + * @type: The setting's type + * @key: The setting's key (both its name and its key in the underlying + * configuration file) + * @optvar: Pointer to the actual value + * @value_destroy: Function use to destroy the value, or %NULL + * @proxy: A #GObject to use as a proxy for the value + * @proxy_prop: Name of the proxy's property to read and write the value + * @destroy_hid: Signal handler identifier for the proxy's ::destroy signal, if + * @proxy is a #GtkObject. + * + * The structure that represents an option. + */ struct _GgdOptEntry { GType type; @@ -48,6 +67,7 @@

typedef struct _GgdOptEntry GgdOptEntry;

+/* syncs an entry's proxy to the entry's value */ static void ggd_opt_entry_sync_to_proxy (GgdOptEntry *entry) { @@ -58,6 +78,7 @@ } }

+/* syncs an entry's value to the entry's proxy value */ static void ggd_opt_entry_sync_from_proxy (GgdOptEntry *entry) { @@ -67,6 +88,14 @@ } }

+/* + * ggd_opt_entry_set_proxy: + * @entry: A #GgdOptEntry + * @proxy: The proxy object + * @prop: The name of the proxy's property to sync with + * + * Sets and syncs the proxy of a #GgdOptEntry. + */ static void ggd_opt_entry_set_proxy (GgdOptEntry *entry, GObject *proxy, @@ -86,6 +115,7 @@ ggd_opt_entry_sync_to_proxy (entry); }

+/* Frees an entry's allocated data */ static void ggd_opt_entry_free_data (GgdOptEntry *entry, gboolean free_opt) @@ -152,7 +182,7 @@ } }

- +/* adds an entry to a group */ static GgdOptEntry * ggd_opt_group_add_entry (GgdOptGroup *group, GType type, @@ -174,6 +204,7 @@ return &g_array_index (group->prefs, GgdOptEntry, group->prefs->len -1); }

+/* looks up for an entry in a group */ static GgdOptEntry * ggd_opt_group_lookup_entry (GgdOptGroup *group, gpointer optvar) @@ -189,6 +220,7 @@ return NULL; }

+/* looks up an entry in a group from is proxy */ static GgdOptEntry * ggd_opt_group_lookup_entry_from_proxy (GgdOptGroup *group, GObject *proxy) @@ -275,6 +307,9 @@ } }

+/* set the proxy of a value + * see the doc of ggd_opt_group_set_proxy_full() that does the same but returns + * a boolean */ static GgdOptEntry * ggd_opt_group_set_proxy_full_internal (GgdOptGroup *group, gpointer optvar, @@ -363,6 +398,7 @@ ggd_opt_group_set_proxy_full_internal (group, optvar, FALSE, 0, NULL, NULL); }

+/* detaches a proxy */ static void ggd_opt_group_remove_proxy_from_proxy (GgdOptGroup *group, GObject *proxy)

Modified: trunk/geanygendoc/src/ggd-options.h =================================================================== --- trunk/geanygendoc/src/ggd-options.h 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-options.h 2010-04-22 15:07:18 UTC (rev 1284) @@ -26,6 +26,11 @@ G_BEGIN_DECLS

+/** + * GgdOptGroup: + * + * Opaque object representing a group of options. + */ typedef struct _GgdOptGroup GgdOptGroup;

Modified: trunk/geanygendoc/src/ggd-tag-utils.c =================================================================== --- trunk/geanygendoc/src/ggd-tag-utils.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-tag-utils.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -75,6 +75,17 @@ GINT_TO_POINTER (direction)); }

+/** + * ggd_tag_find_from_line: + * @tags: A #GPtrArray of TMTag<!-- -->s + * @line: Line for which find the tag + * + * Finds the tag that applies for a given line. + * It actually gets the first tag that precede or is at the exact position of + * the line. + * + * Returns: A #TMTag, or %NULL if none found. + */ TMTag * ggd_tag_find_from_line (const GPtrArray *tags, gulong line) @@ -97,6 +108,15 @@ return tag; }

+/** + * ggd_tag_find_at_current_pos: + * @doc: A #GeanyDocument + * + * Finds the tag that applies for the current position in a #GeanyDocument. + * See ggd_tag_find_from_line(). + * + * Returns: A #TMTag, or %NULL if none found. + */ TMTag * ggd_tag_find_at_current_pos (GeanyDocument *doc) { @@ -110,6 +130,15 @@ return tag; }

+/** + * ggd_tag_find_parent: + * @tags: A #GPtrArray of #TMTag<!-- -->s containing @tag + * @child: A #TMTag, child of the tag to find + * + * Finds the parent tag of a #TMTag. + * + * Returns: A #TMTag, or %NULL if @child have no parent. + */ TMTag * ggd_tag_find_parent (const GPtrArray *tags, const TMTag *child) @@ -180,7 +209,15 @@ { tm_tag_file_t, "file" } };

-/* Tries to convert @type to string. Returns %NULL on failure */ +/** + * ggd_tag_type_get_name: + * @type: A #TMTagType + * + * Tries to convert a #TMTagType to a string. + * + * Returns: A string representing @type that should not be modified or freed, + * or %NULL on failure. + */ const gchar * ggd_tag_type_get_name (TMTagType type) { @@ -195,7 +232,15 @@ return NULL; }

-/* Tries to convert @name to tag type. Returns 0 on failure */ +/** + * ggd_tag_type_from_name: + * @name: A string representing a #TMTag type + * + * Tries to convert string to tag type. + * + * Returns: The #TMTagType that @name stands for, or 0 if @name dosen't stand + * for any type. + */ TMTagType ggd_tag_type_from_name (const gchar *name) { @@ -212,7 +257,14 @@ return 0; }

-/* Gets the name of a tag type */ +/** + * ggd_tag_get_type_name: + * @tag: A #TMTag + * + * Gets the name of a #TMTag's type. See ggd_tag_type_get_name(). + * + * Returns: The #TMTag's type name or %NULL on failure. + */ const gchar * ggd_tag_get_type_name (const TMTag *tag) { @@ -223,17 +275,18 @@

/** * ggd_tag_resolve_type_hierarchy: - * @tags: The tag list that contains @tag + * @tags: The tag array that contains @tag * @tag: A #TMTag to which get the type hierarchy * * Gets the type hierarchy of a tag as a string, each element separated by a * dot. * - * FIXME: perhaps we should use array of type's ID rather than a string. - * FIXME: perhaps drop recursion - * * Returns: the tag's type hierarchy or %NULL if invalid. */ +/* + * FIXME: perhaps we should use array of type's ID rather than a string? + * FIXME: perhaps drop recursion + */ gchar * ggd_tag_resolve_type_hierarchy (const GPtrArray *tags, const TMTag *tag) @@ -357,9 +410,9 @@ * @parent: Tag for which get children * @depth: Maximum depth for children to be found (< 0 means infinite) * + * Finds children tags of a #TMTag. * - * - * Returns: The list of found children + * Returns: The list of children found for @parent */ GList * ggd_tag_find_children (const GPtrArray *tags,

Modified: trunk/geanygendoc/src/ggd-tag-utils.h =================================================================== --- trunk/geanygendoc/src/ggd-tag-utils.h 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-tag-utils.h 2010-04-22 15:07:18 UTC (rev 1284) @@ -26,7 +26,17 @@ G_BEGIN_DECLS

+/** + * GGD_SORT_ASC: + * + * Constant representing ascending sort + */ #define GGD_SORT_ASC (1) +/** + * GGD_SORT_DESC: + * + * Constant representing descending sort + */ #define GGD_SORT_DESC (-1)

void ggd_tag_sort_by_line (GPtrArray *tags,

Modified: trunk/geanygendoc/src/ggd-utils.c =================================================================== --- trunk/geanygendoc/src/ggd-utils.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-utils.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -33,6 +33,14 @@ #include "ggd-plugin.h" /* to access Geany data/funcs */

+/* + * set_file_error_from_errno: + * @error: A #GError + * @errnum: An errno value + * @filename: The file name for which the error applies + * + * Sets a #GError from an errno value, prefixed with a file's name. + */ #define set_file_error_from_errno(error, errnum, filename) \ G_STMT_START { \ gint s_e_f_e_errum = errnum; /* need if @errnum is errno */ \ @@ -41,9 +49,21 @@ "%s: %s", filename, g_strerror (s_e_f_e_errum)); \ } G_STMT_END

-/* copies a file to another place. if @exclusive is %TRUE, copy is done (and - * therefore successful) only if the file doesn't already exist; otherwise, its - * content is overwritten. +/* + * ggd_copy_file: + * @input: Path of the file to copy + * @output: Path of the destination + * @exclusive: %FALSE to override the destination if it already exist, %TRUE + * otherwise + * @mode: Mode to use for creating the file + * @error: Return location for errors, or %NULL to ignore them + * + * Copies a file to a destination. If @exlusive is %TRUE, the destination is not + * overwritten if it exists in a safe way. Otherwise, the destination file is + * simply truncated before the copy, with all the problems that can happen (such + * as partially overwritten file and so). + * + * Returns: %TRUE on success, %FALSE otherwise. */ static gboolean ggd_copy_file (const gchar *input, @@ -101,12 +121,19 @@ return success; }

-/* gets the configuration file path for a given configuration file. - * @name: the configuration file name - * @section: the configuration section or %NULL for the default one - * @prems_req: requested permissions on config file +/** + * ggd_get_config_file: + * @name: The name of the configuration file to get + * @section: The name of the configuration section of the file, or %NULL for the + * default one + * @perms_req: Requested permissions on the configuration file + * @error: Return location for errors, or %NULL to ignore them * - * Returns: the path for the requested configuration file pr %NULL if not found. + * Gets the configuration file path from its name. + * Configuration files may be either the system-wide or the user-specific ones, + * depending on their existence and on the requested permissions. + * + * Returns: The path for the requested configuration file or %NULL if not found. */ gchar * ggd_get_config_file (const gchar *name,

Modified: trunk/geanygendoc/src/ggd-utils.h =================================================================== --- trunk/geanygendoc/src/ggd-utils.h 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd-utils.h 2010-04-22 15:07:18 UTC (rev 1284) @@ -26,6 +26,14 @@ G_BEGIN_DECLS

+/** + * GgdPerms: + * @GGD_PERM_R: Read permission + * @GGD_PERM_W: Write permission + * @GGD_PERM_RW: Both read and write permissions + * + * Flags representing permissions. + */ enum _GgdPerms { GGD_PERM_R = 1 << 0, GGD_PERM_W = 1 << 1,

Modified: trunk/geanygendoc/src/ggd.c =================================================================== --- trunk/geanygendoc/src/ggd.c 2010-04-22 15:06:40 UTC (rev 1283) +++ trunk/geanygendoc/src/ggd.c 2010-04-22 15:07:18 UTC (rev 1284) @@ -266,6 +266,7 @@ return line; }

+/* adjusts the start line of a tag */ static gint adjust_start_line (ScintillaObject *sci, GPtrArray *tags, @@ -321,6 +322,9 @@ return success; }

+/* Gets the #GgdDocSetting that applies for a given tag. + * Since a policy may forward documenting to a parent, tag that actually applies + * is returned in @real_tag. */ static GgdDocSetting * get_setting_from_tag (GgdDocType *doctype, GPtrArray *tag_array, @@ -344,12 +348,12 @@ return setting; }

-/* +/** * ggd_insert_comment: - * @doc: The document to which insert the comment - * @line: SCI's line for which generate a comment. Usually, the current line. + * @doc: The document in which insert the comment + * @line: SCI's line for which generate a comment. Usually the current line. * - * tries to insert a comment + * Tries to insert a comment in a #GeanyDocument. * * <warning> * if tag list is not up-to-date, the result can be surprising

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.