svn commit: r1183386 - /subversion/trunk/subversion/include/svn_sorts.h

[st...@apache.org]

Author: stsp
Date: Fri Oct 14 15:30:20 2011
New Revision: 1183386

URL: http://svn.apache.org/viewvc?rev=1183386&view=rev
Log:
* subversion/include/svn_sorts.h
  (svn_sort__bsearch_lower_bound, svn_sort__array_insert,
   svn_sort__array_delete): Add doxygen markup to docstrings. Explicitly
    mark these functions as private. I don't really like the fact that
    they are declared in a public header, but there is precedent for doing
    so in this file, and moving them to a different header would cause
    more code churn than it's worth.

Modified:
    subversion/trunk/subversion/include/svn_sorts.h

Modified: subversion/trunk/subversion/include/svn_sorts.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_sorts.h?rev=1183386&r1=1183385&r2=1183386&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_sorts.h (original)
+++ subversion/trunk/subversion/include/svn_sorts.h Fri Oct 14 15:30:20 2011
@@ -164,29 +164,38 @@ svn_sort__hash(apr_hash_t *ht,
                                       const svn_sort__item_t *),
                apr_pool_t *pool);
 
-/* Return the lowest index at which the element *KEY should be inserted into
-   the array ARRAY, according to the ordering defined by COMPARE_FUNC.
-   The array must already be sorted in the ordering defined by COMPARE_FUNC.
-   COMPARE_FUNC is defined as for the C stdlib function bsearch(). */
+/* Return the lowest index at which the element @a *key should be inserted into
+ * the array @a array, according to the ordering defined by @a compare_func.
+ * The array must already be sorted in the ordering defined by @a compare_func.
+ * @a compare_func is defined as for the C stdlib function bsearch().
+ *
+ * @note Private. For use by Subversion's own code only.
+ */
 int
 svn_sort__bsearch_lower_bound(const void *key,
                               const apr_array_header_t *array,
                               int (*compare_func)(const void *, const void *));
 
-/* Insert a shallow copy of *NEW_ELEMENT into the array ARRAY at the index
-   INSERT_INDEX, growing the array and shuffling existing elements along to
-   make room. */
+/* Insert a shallow copy of @a *new_element into the array @a array at the index
+ * @a insert_index, growing the array and shuffling existing elements along to
+ * make room.
+ *
+ * @note Private. For use by Subversion's own code only.
+ */
 void
 svn_sort__array_insert(const void *new_element,
                        apr_array_header_t *array,
                        int insert_index);
 
 
-/* Remove ELEMENTS_TO_DELETE elements starting  at DELETE_INDEX from the
-   array ARR. If DELETE_INDEX is not a valid element of ARR,
-   ELEMENTS_TO_DELETE is not greater than zero, or
-   DELETE_INDEX + ELEMENTS_TO_DELETE is greater than ARR->NELTS, then do
-   nothing. */
+/* Remove @a elements_to_delete elements starting at @a delete_index from the
+ * array @a arr. If @a delete_index is not a valid element of @a arr,
+ * @a elements_to_delete is not greater than zero, or
+ * @a delete_index + @a elements_to_delete is greater than @a arr->nelts,
+ * then do nothing.
+ *
+ * @note Private. For use by Subversion's own code only.
+ */
 void
 svn_sort__array_delete(apr_array_header_t *arr,
                        int delete_index,