--- a/liboctave/array/Array.h	Wed Aug 10 17:44:51 2016 +0200
+++ b/liboctave/array/Array.h	Sat Aug 13 12:49:58 2016 +0100
@@ -69,29 +69,42 @@
     ### size() and length()
 
     To access the total number of elements in an Array, use numel()
-    which is short for number of elements and has the same as the
-    Octave function.
+    which is short for number of elements and is equivalent to the
+    Octave function with same name.
+
+    @code{.cc}
+    Array<int> A (dim_vector (10, 20, 4), 1);
+
+    octave_idx_type n = A.numel (); // returns 800 (10x20x4)
 
-    The methods size() and length() do not exist for Array and will not
-    be added (to be more precise, they are currently deprecated).
-    The reason is that such methods cause confusion in the context of
-    a N dimensional array.
+    octave_idx_type nr = A.size (0); // returns 10 (number of rows/dimension 0)
+    octave_idx_type nc = A.size (1); // returns 20 (number of columns)
+    octave_idx_type nc = A.size (2); // returns 4 (size of dimension 3)
+    octave_idx_type l6 = A.size (6); // returns 1 (implicit singleton dimension)
+
+    // Alternatively, get a dim_vector which represents the dimensions.
+    dim_vector dims = A.dims ();
+    @endcode
+
+    The methods size() and length() as they exist in the STL cause
+    confusion in the context of a N dimensional array.
+
+    The size() of an array is the length of all dimensions.  In Octave,
+    the size() function returns a row vector with the length of each
+    dimension, or the size of a specific dimension.  Only the latter is
+    present in liboctave.
 
     Since there is more than 1 dimension, length() would not make sense
     without expliciting which dimension.  If the function existed, which
     length should it return?  Octave length() function returns the length
     of the longest dimension which is an odd definition, only useful for
-    vectors and square matrices.
+    vectors and square matrices.  The alternatives numel(), rows(),
+    columns(), and size(d) are more explict and recommended.
 
-    The size() of an array is the length of all dimensions.  In Octave
-    the size() function returns a row vector with the length of each
-    dimension.  Use dims() to get a dim_vector representing the Array
-    dimensions.
+    ### size_type
 
-    ### size type
-
-    Octave's "size type", is octave_idx_type which is a typedef for int
-    or long int, depending whether Octave was configured for 64-bit
+    Array::size_type is `octave_idx_type` which is a typedef for `int`
+    or `long int`, depending whether Octave was configured for 64-bit
     indexing.
 
     This is a signed integer which may cause problems when mixed with
@@ -185,6 +198,12 @@
 
   typedef T element_type;
 
+  typedef T value_type;
+
+  //! Used for operator(), and returned by numel() and size()
+  //! (beware: signed integer)
+  typedef octave_idx_type size_type;
+
   typedef typename ref_param<T>::type crefT;
 
   typedef bool (*compare_fcn_type) (typename ref_param<T>::type,
@@ -399,6 +418,20 @@
   octave_idx_type pages (void) const { return dim3 (); }
   //@}
 
+  //! Size of the specified dimension.
+  /*!
+      Dimensions beyond the Array number of dimensions return 1 as
+      those are implicit singleton dimensions.
+
+      Equivalent to Octave's `size (A, DIM)`
+  */
+  size_type size (const size_type d) const
+  {
+    // Should we throw for negative values?
+    // Should >= ndims () be handled by dim_vector operator() instead ?
+    return d >= ndims () ? 1 : dimensions(d);
+  }
+
   size_t byte_size (void) const
   { return static_cast<size_t> (numel ()) * sizeof (T); }