[geany/geany] 63a2f0: Merge branch 'ntrel/doc-macro-examples'

[Colomban Wendling]

Branch:      refs/heads/master
Author:      Colomban Wendling <ban at herbesfolles.org>
Committer:   Colomban Wendling <ban at herbesfolles.org>
Date:        Sun, 27 Apr 2014 16:06:01 UTC
Commit:      63a2f075f6c910add7f56e69c9d24b2757aee5fa
             https://github.com/geany/geany/commit/63a2f075f6c910add7f56e69c9d24b2757aee5fa

Log Message:
-----------
Merge branch 'ntrel/doc-macro-examples'


Modified Paths:
--------------
    src/document.c
    src/document.h

Modified: src/document.c
6 lines changed, 4 insertions(+), 2 deletions(-)
===================================================================
@@ -88,7 +88,9 @@ GeanyFilePrefs file_prefs;
  * although usually you would just use the foreach_document() macro.
  *
  * 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(). */
+ * Notebook tabs can be reordered. Use @c document_get_from_page().
+ *
+ * @see documents. */
 GPtrArray *documents_array = NULL;
 
 
@@ -2829,7 +2831,7 @@ const GdkColor *document_get_status_color(GeanyDocument *doc)
 }
 
 
-/** Accessor function for @ref GeanyData::documents_array items.
+/** Accessor function for @ref documents_array items.
  * @warning Always check the returned document is valid (@c doc->is_valid).
  * @param idx @c documents_array index.
  * @return The document, or @c NULL if @a idx is out of range.


Modified: src/document.h
20 lines changed, 16 insertions(+), 4 deletions(-)
===================================================================
@@ -118,9 +118,11 @@ struct GeanyDocument
 extern GPtrArray *documents_array;
 
 
-/** Wraps documents_array so it can be used with C array syntax.
- * Example: documents[0]->sci = NULL;
- * @see document_index(). */
+/** Wraps @ref documents_array so it can be used with C array syntax.
+ * @warning Always check the returned document is valid (@c doc->is_valid).
+ *
+ * Example: @code GeanyDocument *doc = documents[i]; @endcode
+ * @see documents_array(). */
 #define documents ((GeanyDocument **)GEANY(documents_array)->pdata)
 
 /** @deprecated Use @ref foreach_document() instead.
@@ -133,7 +135,17 @@ extern GPtrArray *documents_array;
 
 /** Iterates all valid documents.
  * Use like a @c for statement.
- * @param i @c guint index for document_index(). */
+ * @param i @c guint index for @ref documents_array.
+ *
+ * Example:
+ * @code
+ * guint i;
+ * foreach_document(i)
+ * {
+ * 	GeanyDocument *doc = documents[i];
+ * 	g_assert(doc->is_valid);
+ * }
+ * @endcode */
 #define foreach_document(i) \
 	for (i = 0; i < GEANY(documents_array)->len; i++)\
 		if (!documents[i]->is_valid)\



--------------
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).