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.


git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@2812 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -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>

src/document.c

@@ -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 @@ static void document_redo_add(GeanyDocument *doc, guint type, gpointer data);
 #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 @@ static gchar *get_real_path_from_utf8(const gchar *utf8_filename)
 
 
 /**
- *  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 @@ GeanyDocument *document_find_by_sci(ScintillaObject *sci)
 }
 
 
-/* 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 @@ gint document_get_notebook_page(GeanyDocument *doc)
 
 
 /**
- *  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 @@ static void queue_colourise(GeanyDocument *doc)
 
 
 /* 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;

src/document.h

@@ -107,10 +107,9 @@ struct GeanyDocument
 	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;

src/plugindata.h

@@ -154,7 +154,7 @@ typedef struct GeanyData
 {
 	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 */