SF.net SVN: geany:[2812] trunk

[ntrel at users.sourceforge.net]

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.