SF.net SVN: geany:[3160] trunk

Revision: 3160 http://geany.svn.sourceforge.net/geany/?rev=3160&view=rev Author: eht16 Date: 2008-10-27 19:17:28 +0000 (Mon, 27 Oct 2008)

Log Message: ----------- Enable generation of API documentation of tagmanager functions which are exposed in the plugin API, hide all others from the API docs.

Modified Paths: -------------- trunk/ChangeLog trunk/doc/Doxyfile.in trunk/tagmanager/include/tm_source_file.h trunk/tagmanager/include/tm_work_object.h trunk/tagmanager/include/tm_workspace.h trunk/tagmanager/tm_source_file.c trunk/tagmanager/tm_work_object.c trunk/tagmanager/tm_workspace.c

Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/ChangeLog 2008-10-27 19:17:28 UTC (rev 3160) @@ -6,6 +6,13 @@ Replace deprecated gtk_marshal_* functions with g_cclosure_marshal_* functions and add geany_cclosure_marshal_VOID__STRING_INT_POINTER. Fix a wrong marshal type (pointer != int). + * doc/Doxyfile.in, tagmanager/include/tm_source_file.h, + tagmanager/include/tm_work_object.h, + tagmanager/include/tm_workspace.h, tagmanager/tm_source_file.c, + tagmanager/tm_work_object.c, tagmanager/tm_workspace.c: + Enable generation of API documentation of tagmanager functions + which are exposed in the plugin API, hide all others from the + API docs.

2008-10-26 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>

Modified: trunk/doc/Doxyfile.in =================================================================== --- trunk/doc/Doxyfile.in 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/doc/Doxyfile.in 2008-10-27 19:17:28 UTC (rev 3160) @@ -95,7 +95,10 @@ #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = ../src/ ./ ../plugins/pluginmacros.h +INPUT = ../src/ ./ ../plugins/pluginmacros.h \ + ../tagmanager/tm_source_file.c ../tagmanager/include/tm_source_file.h \ + ../tagmanager/tm_work_object.c ../tagmanager/include/tm_work_object.h \ + ../tagmanager/tm_workspace.c ../tagmanager/include/tm_workspace.h INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c \ *.cc \

Modified: trunk/tagmanager/include/tm_source_file.h =================================================================== --- trunk/tagmanager/include/tm_source_file.h 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/tagmanager/include/tm_source_file.h 2008-10-27 19:17:28 UTC (rev 3160) @@ -12,15 +12,7 @@

#include "tm_work_object.h"

-/*! \file - The TMSourceFile structure and associated functions are used to maintain - tags for individual files. See the test file tm_source_file_test.c included - below for an example of how to use this structure and the related functions.

- \include tm_tag_print.c - -*/ - #ifndef LIBCTAGS_DEFINED typedef int langType; typedef void tagEntryInfo; @@ -34,21 +26,14 @@ { #endif

-/*! Casts a pointer to a pointer to a TMSourceFile structure */ +/* Casts a pointer to a pointer to a TMSourceFile structure */ #define TM_SOURCE_FILE(work_object) ((TMSourceFile *) work_object)

-/*! Checks whether the object is a TMSourceFile */ +/* Checks whether the object is a TMSourceFile */ #define IS_TM_SOURCE_FILE(source_file) (((TMWorkObject *) (source_file))->type \ == source_file_class_id)

/*! - This example demonstrates the use of the TMSourceFile structure. When run, - it outputs the tags encountered in the source files specified in the command line. - - \example tm_tag_print.c -*/ - -/*! The TMSourceFile structure is derived from TMWorkObject and contains all it's attributes, plus an integer representing the language of the file. */ @@ -59,20 +44,21 @@ gboolean inactive; /*!< Whether this file should be scanned for tags */ } TMSourceFile;

-/*! Initializes a TMSourceFile structure from a file name. */ + +/* Initializes a TMSourceFile structure from a file name. */ gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_name, gboolean update, const char *name);

-/*! Initializes a TMSourceFile structure and returns a pointer to it. */ +/* Initializes a TMSourceFile structure and returns a pointer to it. */ TMWorkObject *tm_source_file_new(const char *file_name, gboolean update, const char *name);

-/*! Destroys the contents of the source file. Note that the tags are owned by the +/* Destroys the contents of the source file. Note that the tags are owned by the source file and are also destroyed when the source file is destroyed. If pointers to these tags are used elsewhere, then those tag arrays should be rebuilt. */ void tm_source_file_destroy(TMSourceFile *source_file);

-/*! Frees a TMSourceFile structure, including all contents */ +/* Frees a TMSourceFile structure, including all contents */ void tm_source_file_free(gpointer source_file);

/*! Updates the source file by reparsing if the modification time is greater @@ -92,14 +78,14 @@ gboolean tm_source_file_update(TMWorkObject *source_file, gboolean force , gboolean recurse, gboolean update_parent);

-/*! Parses the source file and regenarates the tags. +/* Parses the source file and regenarates the tags. \param source_file The source file to parse \return TRUE on success, FALSE on failure \sa tm_source_file_update() */ gboolean tm_source_file_parse(TMSourceFile *source_file);

-/*! +/* This function is registered into the ctags parser when a file is parsed for the first time. The function is then called by the ctags parser each time it finds a new tag. You should not have to use this function. @@ -107,23 +93,23 @@ */ int tm_source_file_tags(const tagEntryInfo *tag);

-/*! +/* Writes all tags of a source file (including the file tag itself) to the passed file pointer. \param source_file The source file to write. \param fp The file pointer to write to. - \attrs The attributes to write. + \param attrs The attributes to write. \return TRUE on success, FALSE on failure. */ gboolean tm_source_file_write(TMWorkObject *source_file, FILE *fp, guint attrs);

-/*! Contains the id obtained by registering the TMSourceFile class as a child of +/* Contains the id obtained by registering the TMSourceFile class as a child of TMWorkObject. \sa tm_work_object_register() */ extern guint source_file_class_id;

-/*! Gets the name associated with the language index. +/* Gets the name associated with the language index. \param lang The language index. \return The language name, or NULL. */

Modified: trunk/tagmanager/include/tm_work_object.h =================================================================== --- trunk/tagmanager/include/tm_work_object.h 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/tagmanager/include/tm_work_object.h 2008-10-27 19:17:28 UTC (rev 3160) @@ -19,10 +19,10 @@ { #endif

-/*! Evaluates to X is X is defined, else evaluates to Y */ +/* Evaluates to X is X is defined, else evaluates to Y */ #define NVL(X,Y) (X)?(X):(Y)

-/*! Macro to cast a pointer to (TMWorkObject *) */ +/* Macro to cast a pointer to (TMWorkObject *) */ #define TM_WORK_OBJECT(work_object) ((TMWorkObject *) work_object)

/*! @@ -41,7 +41,7 @@ GPtrArray *tags_array; /*!< Tags obtained by parsing the object */ } TMWorkObject;

-/*! Prototype of the update function required to be written by all classes +/* Prototype of the update function required to be written by all classes derived from TMWorkObject. The function should take a pointer to the object and a flag indicating whether the cache should be ignored, and update the object's tag array accordingly. @@ -51,7 +51,7 @@ typedef gboolean (*TMUpdateFunc) (TMWorkObject *work_object, gboolean force , gboolean recurse, gboolean update_parent);

-/*! Prototype of the find function required to be written by all classed +/* Prototype of the find function required to be written by all classed derived from TMWorkObject. The function should take a pointer to the work object and a file name and return a pointer to the work object corresponding to the file name if the file is part of the object, and NULL otherwise. @@ -60,7 +60,7 @@ typedef TMWorkObject *(*TMFindFunc) (TMWorkObject *work_object, const char *file_name , gboolean name_only);

-/*! +/* Contains pointers to functions necessary to handle virtual function calls correctly. To create a new object derived from TMWorkObject, you need to write the three functions specified as the members of this class and @@ -73,9 +73,9 @@ TMFindFunc find_func; /*!< Function to locate contained work objects */ } TMWorkObjectClass;

-#define TM_OBJECT_TYPE(work_object) ((TMWorkObject *) work_object)->type /*!< Type of the work object */ -#define TM_OBJECT_FILE(work_object) ((TMWorkObject *) work_object)->file_name /*!< File name of the work object */ -#define TM_OBJECT_TAGS(work_object) ((TMWorkObject *) work_object)->tags_array /*!< Tag array of the work object */ +#define TM_OBJECT_TYPE(work_object) ((TMWorkObject *) work_object)->type /*< Type of the work object */ +#define TM_OBJECT_FILE(work_object) ((TMWorkObject *) work_object)->file_name /*< File name of the work object */ +#define TM_OBJECT_TAGS(work_object) ((TMWorkObject *) work_object)->tags_array /*< Tag array of the work object */

/*! Given a file name, returns a newly allocated string containing the realpath() @@ -86,7 +86,7 @@ */ gchar *tm_get_real_path(const gchar *file_name);

-/*! +/* Initializes the work object structure. This function should be called by the initialization routine of the derived classes to ensure that the base members are initialized properly. The library user should not have to call this under @@ -101,7 +101,7 @@ gboolean tm_work_object_init(TMWorkObject *work_object, guint type, const char *file_name , gboolean create);

-/*! +/* Initializes a new TMWorkObject structure and returns a pointer to it. You shouldn't have to call this function. \return NULL on failure @@ -109,14 +109,14 @@ */ TMWorkObject *tm_work_object_new(guint type, const char *file_name, gboolean create);

-/*! +/* Utility function - Given a file name, returns the timestamp of modification. \param file_name Full path to the file. \return Timestamp of the file's modification time. 0 on failure. */ time_t tm_get_file_timestamp(const char *file_name);

-/*! +/* Checks if the work object has been modified since the last update by comparing the timestamp stored in the work object structure with the modification time of the physical file. @@ -125,7 +125,7 @@ */ gboolean tm_work_object_is_changed(TMWorkObject *work_object);

-/*! +/* Destroys a work object's data without freeing the structure itself. It should be called by the deallocator function of classes derived from TMWorkObject. The user shouldn't have to call this function. @@ -140,7 +140,7 @@ */ void tm_work_object_free(gpointer work_object);

-/*! +/* This function should be called exactly once by all classes derived from TMWorkObject, since it supplies a unique ID on each call and stores the functions to call for updation and deallocation of objects of the type allocated. The user should not @@ -153,7 +153,7 @@ */ guint tm_work_object_register(GFreeFunc free_func, TMUpdateFunc update_func, TMFindFunc find_func);

-/*! +/* Writes the tags for the work object to the file specified. \param work_object The work object whose tags need to be written. \param file The file to which the tags are to be written. @@ -161,7 +161,7 @@ */ void tm_work_object_write_tags(TMWorkObject *work_object, FILE *file, guint attrs);

-/*! +/* Updates the tags array if necessary. Automatically calls the update function of the type to which the object belongs. \param work_object Pointer to a work object or an object derived from it. @@ -175,7 +175,7 @@ gboolean tm_work_object_update(TMWorkObject *work_object, gboolean force , gboolean recurse, gboolean update_parent);

-/*! +/* Finds the work object corresponding to the file name passed and returns a pointer to it. If not found, returns NULL. This is a virtual function which automatically calls the registered find function of teh derived object. @@ -184,7 +184,7 @@ TMWorkObject *tm_work_object_find(TMWorkObject *work_object, const char *file_name , gboolean name_only);

-/*! Dumps the contents of a work object - useful for debugging */ +/* Dumps the contents of a work object - useful for debugging */ void tm_work_object_dump(const TMWorkObject *w);

#ifdef __cplusplus

Modified: trunk/tagmanager/include/tm_workspace.h =================================================================== --- trunk/tagmanager/include/tm_workspace.h 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/tagmanager/include/tm_workspace.h 2008-10-27 19:17:28 UTC (rev 3160) @@ -7,6 +7,7 @@ * */

+ #ifndef TM_WORKSPACE_H #define TM_WORKSPACE_H

@@ -14,28 +15,12 @@

#include "tm_work_object.h"

-/*! \file - The TMWorkspace structure is meant to be used as a singleton to store application - wide tag information. The workspace is intended to contain a list of global tags - and a set of work objects (projects or individual files). You need not use the - workspace, though, to use tag manager, unless you need things like global tags - and a place to store all current open projects and individual files. TMWorkspace - is derived from TMWorkObject. - - The following example demonstrates the use of workspace functions to create global tags. - \include tm_global_tags.c -*/ - #ifdef __cplusplus extern "C" { #endif

-/*! - This example demonstrates the use of the global tag generation function.

- \example tm_global_tags.c -*/

/*! The Tag Manager Workspace. This is a singleton work object containing a list of work objects. These can be either individual files or project containing @@ -50,7 +35,7 @@ GPtrArray *work_objects; /*!< An array of TMWorkObject pointers */ } TMWorkspace;

-/*! Since TMWorkspace is a singleton, you should not create multiple +/* Since TMWorkspace is a singleton, you should not create multiple workspaces, but get a pointer to the workspace whenever required. The first time a pointer is requested, or a work object is added to the workspace, a workspace is created. Subsequent calls to the function will return the @@ -64,7 +49,7 @@ */ gboolean tm_workspace_add_object(TMWorkObject *work_object);

-/*! Given a file name, returns a pointer to the object if the object's file +/* Given a file name, returns a pointer to the object if the object's file name is same as the passed file name, otherwise retruns NULL. This is an overloaded version of tm_work_object_find(). \param work_object Pointer to the workspace. @@ -84,7 +69,7 @@ */ gboolean tm_workspace_remove_object(TMWorkObject *work_object, gboolean free, gboolean update);

-/*! Loads the global tag list from the specified file. The global tag list should +/* Loads the global tag list from the specified file. The global tag list should have been first created using tm_workspace_create_global_tags(). \param tags_file The file containing global tags. \return TRUE on success, FALSE on failure. @@ -93,7 +78,7 @@ gboolean tm_workspace_load_global_tags(const char *tags_file, gint mode); /*gboolean tm_workspace_load_global_tags(const char *tags_file);*/

-/*! Creates a list of global tags. Ideally, this should be created once during +/* Creates a list of global tags. Ideally, this should be created once during installations so that all users can use the same file. Thsi is because a full scale global tag list can occupy several megabytes of disk space. \param pre_process The pre-processing command. This is executed via system(), @@ -107,13 +92,13 @@ gboolean tm_workspace_create_global_tags(const char *config_dir, const char *pre_process, const char **includes, int includes_count, const char *tags_file, int lang);

-/*! Recreates the tag array of the workspace by collecting the tags of +/* Recreates the tag array of the workspace by collecting the tags of all member work objects. You shouldn't have to call this directly since this is called automatically by tm_workspace_update(). */ void tm_workspace_recreate_tags_array(void);

-/*! Calls tm_work_object_update() for all workspace member work objects. +/* Calls tm_work_object_update() for all workspace member work objects. Use if you want to globally refresh the workspace. \param workspace Pointer to the workspace. \param force Whether the cache should be ignored. @@ -125,10 +110,10 @@ gboolean tm_workspace_update(TMWorkObject *workspace, gboolean force , gboolean recurse, gboolean update_parent);

-/*! Dumps the workspace tree - useful for debugging */ +/* Dumps the workspace tree - useful for debugging */ void tm_workspace_dump(void);

-/*! Returns all matching tags found in the workspace. +/* Returns all matching tags found in the workspace. \param name The name of the tag to find. \param type The tag types to return (TMTagType). Can be a bitmask. \param attrs The attributes to sort and dedup on (0 terminated integer array). @@ -140,7 +125,7 @@ const GPtrArray *tm_workspace_find(const char *name, int type, TMTagAttrType *attrs , gboolean partial, langType lang);

-/*! Returns all matching tags found in the workspace. +/* Returns all matching tags found in the workspace. \param name The name of the tag to find. \param scope The scope name of the tag to find, or NULL. \param type The tag types to return (TMTagType). Can be a bitmask. @@ -154,23 +139,23 @@ tm_workspace_find_scoped (const char *name, const char *scope, gint type, TMTagAttrType *attrs, gboolean partial, langType lang, gboolean global_search);

-/*! Returns TMTag to function which "own" given line +/* Returns TMTag to function which "own" given line \param line Current line in edited file. \param file_tags A GPtrArray of edited file TMTag pointers. \return TMTag pointers to owner function. */ const TMTag *tm_get_current_function(GPtrArray *file_tags, const gulong line);

-/*! Returns a list of parent classes for the given class name +/* Returns a list of parent classes for the given class name \param name Name of the class \return A GPtrArray of TMTag pointers (includes the TMTag for the class) */ const GPtrArray *tm_workspace_get_parents(const gchar *name);

-/*! Frees the workspace structure and all child work objects. Use only when +/* Frees the workspace structure and all child work objects. Use only when exiting from the main program. */ void tm_workspace_free(gpointer workspace);

-/*! Contains the id obtained by registering the TMWorkspace class as a child of +/* Contains the id obtained by registering the TMWorkspace class as a child of TMWorkObject. \sa tm_work_object_register() */

Modified: trunk/tagmanager/tm_source_file.c =================================================================== --- trunk/tagmanager/tm_source_file.c 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/tagmanager/tm_source_file.c 2008-10-27 19:17:28 UTC (rev 3160) @@ -7,6 +7,13 @@ * */

+/** + * @file tm_source_file.h + The TMSourceFile structure and associated functions are used to maintain + tags for individual files. +*/ + + #include <stdio.h> #include <limits.h> #include <stdlib.h>

Modified: trunk/tagmanager/tm_work_object.c =================================================================== --- trunk/tagmanager/tm_work_object.c 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/tagmanager/tm_work_object.c 2008-10-27 19:17:28 UTC (rev 3160) @@ -7,6 +7,11 @@ * */

+/** + * @file tm_work_object.h + * A TMWorkObject structure is the base class for TMSourceFile and TMProject. +*/ + #include "general.h" /* must always come first */

#include <stdio.h>

Modified: trunk/tagmanager/tm_workspace.c =================================================================== --- trunk/tagmanager/tm_workspace.c 2008-10-27 19:17:11 UTC (rev 3159) +++ trunk/tagmanager/tm_workspace.c 2008-10-27 19:17:28 UTC (rev 3160) @@ -7,6 +7,18 @@ * */

+/*! + * @file tm_workspace.h + The TMWorkspace structure is meant to be used as a singleton to store application + wide tag information. + + The workspace is intended to contain a list of global tags + and a set of work objects (projects or individual files). You need not use the + workspace, though, to use tag manager, unless you need things like global tags + and a place to store all current open projects and individual files. TMWorkspace + is derived from TMWorkObject. +*/ + #include "general.h"

#include <stdio.h>

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