Revision: 2812 http://geany.svn.sourceforge.net/geany/?rev=2812&view=rev Author: ntrel Date: 2008-07-24 15:17:55 +0000 (Thu, 24 Jul 2008)

Log Message: ----------- Add more dox explaining how to use documents_array (moved from document.h, to minimise rebuilding after adding dox). Remove some mentions of document indexes in document.c comments.

Modified Paths: -------------- trunk/ChangeLog trunk/src/document.c trunk/src/document.h trunk/src/plugindata.h

Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2008-07-24 14:37:36 UTC (rev 2811) +++ trunk/ChangeLog 2008-07-24 15:17:55 UTC (rev 2812) @@ -13,6 +13,10 @@ Add dox for GeanyApp, GeanyProject. Move GeanyProject typedef to project.h, as it is rarely used without including project.h. + * src/plugindata.h, src/document.c, src/document.h: + Add more dox explaining how to use documents_array (moved from + document.h, to minimise rebuilding after adding dox). + Remove some mentions of document indexes in document.c comments.

2008-07-23 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>

Modified: trunk/src/document.c =================================================================== --- trunk/src/document.c 2008-07-24 14:37:36 UTC (rev 2811) +++ trunk/src/document.c 2008-07-24 15:17:55 UTC (rev 2812) @@ -74,6 +74,16 @@

GeanyFilePrefs file_prefs;

+/** Dynamic array of GeanyDocument pointers holding information about the notebook tabs. + * Once a pointer is added to this, it is never freed. This means you can keep a pointer + * to a document over time, but it might no longer represent a notebook tab. To check this, + * check @c doc_ptr->is_valid. Of course, the pointer may represent a different + * file by then. + * + * You also need to check @c GeanyDocument::is_valid when iterating over this array. + * + * Never assume that the order of document pointers is the same as the order of notebook tabs. + * Notebook tabs can be reordered. Use @c document_get_from_page(). */ GPtrArray *documents_array;

@@ -99,7 +109,7 @@ #endif

/** - * Find and retrieve the index of the given filename in the %document list. + * Find and retrieve a document with the given filename from the document list. * * @param realname The filename to search, which should be identical to the * string returned by @c tm_get_real_path(). @@ -142,7 +152,7 @@

/** - * Find and retrieve the index of the given filename in the %document list. + * Find and retrieve a document with the given filename from the document list. * This matches either an exact GeanyDocument::file_name string, or variant * filenames with relative elements in the path (e.g. @c "/dir/..//name" will * match @c "/name"). @@ -199,7 +209,7 @@ }

-/* returns the index of the notebook page from the document index */ +/* returns the index of the notebook page for the document. */ gint document_get_notebook_page(GeanyDocument *doc) { if (doc == NULL) @@ -211,7 +221,7 @@

/** - * Find and retrieve the index of the given notebook page @a page_num in the %document list. + * Find and retrieve the document for the given notebook page @a page_num. * * @param page_num The notebook page number to search. * @@ -381,7 +391,7 @@

/* Creates a new document and editor, adding a tab in the notebook. - * @return The index of the created document */ + * @return The created document */ static GeanyDocument *document_create(const gchar *utf8_filename) { GeanyDocument *this;

Modified: trunk/src/document.h =================================================================== --- trunk/src/document.h 2008-07-24 14:37:36 UTC (rev 2811) +++ trunk/src/document.h 2008-07-24 15:17:55 UTC (rev 2812) @@ -107,10 +107,9 @@ gchar *real_path; };

- -/** Dynamic array of GeanyDocument pointers holding information about the notebook tabs. */ extern GPtrArray *documents_array;

+ /** * This wraps documents_array so it can be used with C array syntax. * Example: documents[0]->sci = NULL;

Modified: trunk/src/plugindata.h =================================================================== --- trunk/src/plugindata.h 2008-07-24 14:37:36 UTC (rev 2811) +++ trunk/src/plugindata.h 2008-07-24 15:17:55 UTC (rev 2812) @@ -154,7 +154,7 @@ { struct GeanyApp *app; /**< Geany application data fields */ struct GeanyMainWidgets *main_widgets; /**< Important widgets in the main window */ - GPtrArray *documents_array; /**< Dynamic array of GeanyDocument pointers */ + GPtrArray *documents_array; /**< See document.h#documents_array. */ GPtrArray *filetypes_array; /**< Dynamic array of GeanyFiletype pointers */ struct GeanyPrefs *prefs; /**< General settings */ struct GeanyInterfacePrefs *interface_prefs; /**< Interface settings */

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