From 5ff38b4daa332b1d90af991dd369857df3798b70 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <nick.treleaven@btinternet.com>
Date: Thu, 31 Oct 2013 14:14:00 +0000
Subject: [PATCH] Fix document pointer documentation

Improve clarity and remove wrong documentation about using `is_valid` to
check if a document still exists.
---
 src/document.c | 15 ++++++++-------
 src/document.h |  8 +++-----
 2 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/src/document.c b/src/document.c
index d2c55bff0a..50b25aac8f 100644
--- a/src/document.c
+++ b/src/document.c
@@ -78,17 +78,18 @@
 
 GeanyFilePrefs file_prefs;
 
-/** Dynamic array of GeanyDocument pointers holding information about the notebook tabs.
+/** Dynamic array of GeanyDocument pointers.
  * 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.
+ * to a document over time, but it may represent a different
+ * document later on, or may have been closed and become invalid.
  *
- * You also need to check @c GeanyDocument::is_valid when iterating over this array,
- * although usually you would just use the foreach_document() macro.
+ * @warning You must check @c GeanyDocument::is_valid when iterating over this array.
+ * This is done automatically if you use the foreach_document() macro.
  *
+ * @note
  * 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().
+ * One reason is that notebook tabs can be reordered.
+ * Use @c document_get_from_page() to lookup a document from a notebook tab number.
  *
  * @see documents. */
 GPtrArray *documents_array = NULL;
diff --git a/src/document.h b/src/document.h
index 4b639f02b9..3995a39287 100644
--- a/src/document.h
+++ b/src/document.h
@@ -77,7 +77,7 @@ extern GeanyFilePrefs file_prefs;
  **/
 struct GeanyDocument
 {
-	/** General flag to represent this document is active and all properties are set correctly. */
+	/** Flag used to check if this document is valid when iterating @ref documents_array. */
 	gboolean		 is_valid;
 	gint			 index;		/**< Index in the documents array. */
 	/** Whether this document supports source code symbols(tags) to show in the sidebar. */
@@ -133,7 +133,7 @@ extern GPtrArray *documents_array;
 #define documents_foreach(i) foreach_document(i)
 #endif
 
-/** Iterates all valid documents.
+/** Iterates all valid document indexes.
  * Use like a @c for statement.
  * @param i @c guint index for @ref documents_array.
  *
@@ -152,9 +152,7 @@ extern GPtrArray *documents_array;
 			{}\
 		else /* prevent outside 'else' matching our macro 'if' */
 
-/** @c NULL-safe way to check @c doc_ptr->is_valid.
- * This is useful when @a doc_ptr was stored some time earlier and documents may have been
- * closed since then.
+/** Null-safe way to check @ref GeanyDocument::is_valid.
  * @note This should not be used to check the result of the main API functions,
  * these only need a NULL-pointer check - @c document_get_current() != @c NULL. */
 #define DOC_VALID(doc_ptr) \