# HG changeset patch
# User Piotr Held <pjheld@gmail.com>
# Date 1432138520 21600
# Node ID 6af35d4f1ba4c70b4c722294ec873124a3d2e9e9
# Parent  eae5e4d58740e596fbedd972c120ac8f866ef6ab
doxygen: document Array::length() and similar methods (bug #45138)

* liboctave/array/Array.h: make special note that Array::length() is different
from length() at the Octave interpreter.  Also document capacity, nelem, and
numel.

diff -r eae5e4d58740 -r 6af35d4f1ba4 liboctave/array/Array.h
--- a/liboctave/array/Array.h	Wed May 20 22:40:11 2015 +0200
+++ b/liboctave/array/Array.h	Wed May 20 10:15:20 2015 -0600
@@ -249,11 +249,29 @@
   void clear (octave_idx_type r, octave_idx_type c)
   { clear (dim_vector (r, c)); }
 
+  // Number of elements in the array. These are all synonyms.
   //@{
-  //! Number of elements in the array. These are all synonyms.
+  //! Number of elements in the array.
+  //! Synonymous with length(), nelem(), and numel().
   octave_idx_type capacity (void) const { return slice_len; }
+
+  //! Number of elements in the array.
+  /*! Synonymous with capacity(), nelem(), and numel().
+
+      @note
+      This is @em not the same as @c %length() at the Octave interpreter.
+      At the Octave interpreter, the function @c %length() returns the
+      length of the greatest dimension.  This method returns the total
+      number of elements.
+   */
   octave_idx_type length (void) const { return capacity (); }
+
+  //! Number of elements in the array.
+  //! Synonymous with capacity(), length(), and numel().
   octave_idx_type nelem (void) const { return capacity (); }
+
+  //! Number of elements in the array.
+  //! Synonymous with capacity(), length(), and nelem().
   octave_idx_type numel (void) const { return nelem (); }
   //@}