SF.net SVN: geany-plugins:[1284] trunk/geanygendoc/src
colombanw at users.sourceforge.net
colombanw at xxxxx
Thu Apr 22 15:07:18 UTC 2010
Revision: 1284
http://geany-plugins.svn.sourceforge.net/geany-plugins/?rev=1284&view=rev
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.
More information about the Plugins-Commits
mailing list