From 5e4c8e0adefde17036e42c077d3174bd06a21a12 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <nick.treleaven@btinternet.com>
Date: Wed, 13 Apr 2011 12:16:02 +0000
Subject: [PATCH] Update dox for document_compare_by_display_name() with
 warning about parameter addresses.

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@5718 ea778897-0a13-0410-b9d1-a72fbfd435f5
---
 ChangeLog      |  7 +++++++
 src/document.c | 15 ++++++++-------
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index db5a3211..1cdf730d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2011-04-13  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
+
+ * src/document.c:
+   Update dox for document_compare_by_display_name() with warning
+   about parameter addresses.
+
+
 2011-04-12  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>
 
  * src/document.c:
diff --git a/src/document.c b/src/document.c
index 9079a7a6..6ad0dc54 100644
--- a/src/document.c
+++ b/src/document.c
@@ -3013,15 +3013,16 @@ gboolean document_check_disk_status(GeanyDocument *doc, gboolean force)
 }
 
 
-/** GCompareFunc-like sort function to sort documents, e.g. in a GPtrArray by
- *  their display names.
- *  Display names means the base name of the document's file.
+/** Compares documents by their display names.
+ * This matches @c GCompareFunc for use with e.g. @c g_ptr_array_sort().
+ * @note 'Display name' means the base name of the document's filename.
  *
- * @param a @c document a.
- * @param b @c document b.
- * @return negative value if a < b; zero if a = b; positive value if a > b.
+ * @param a @c GeanyDocument**.
+ * @param b @c GeanyDocument**.
+ * @warning The arguments take the address of each document pointer.
+ * @return Negative value if a < b; zero if a = b; positive value if a > b.
  *
- *  @since 0.21
+ * @since 0.21
  */
 gint document_compare_by_display_name(gconstpointer a, gconstpointer b)
 {