Branch: refs/heads/master Author: Nick Treleaven nick.treleaven@btinternet.com Committer: Nick Treleaven nick.treleaven@btinternet.com Date: Mon, 28 Apr 2014 11:34:13 UTC Commit: 5ff38b4daa332b1d90af991dd369857df3798b70 https://github.com/geany/geany/commit/5ff38b4daa332b1d90af991dd369857df3798b...

Log Message: ----------- Fix document pointer documentation

Improve clarity and remove wrong documentation about using `is_valid` to check if a document still exists.

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

Modified: src/document.c 15 lines changed, 8 insertions(+), 7 deletions(-) =================================================================== @@ -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;

Modified: src/document.h 8 lines changed, 3 insertions(+), 5 deletions(-) =================================================================== @@ -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) \

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