--- a/liboctave/Array.h
+++ b/liboctave/Array.h
@@ -107,6 +107,13 @@
 
   dim_vector dimensions;
 
+  // Rationale:
+  // slice_data is a pointer to rep->data, denoting together with slice_len the
+  // actual portion of the data referenced by this Array<T> object. This allows
+  // to make shallow copies not only of a whole array, but also of contiguous
+  // subranges. Every time rep is directly manipulated, slice_data and slice_len
+  // need to be properly updated.
+
   T* slice_data;
   octave_idx_type slice_len;
 

--- a/liboctave/ChangeLog
+++ b/liboctave/ChangeLog
@@ -1,3 +1,8 @@
+2009-01-17  Jaroslav Hajek  <highegg@gmail.com>
+
+	* Array.h (Array<T>): Document internal use of slice_data and
+	slice_len.
+
 2009-01-15  John W. Eaton  <jwe@octave.org>
 
 	* Sparse.cc (Sparse<T>::reshape): Include mismatched dimensions in

--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,8 @@
+2009-01-17  Jaroslav Hajek  <highegg@gmail.com>
+
+	* ov.h: Describe usage of storable_value and make_storable_value.
+	* ov.cc: Remove FIXME comment.
+
 2009-01-15  John W. Eaton  <jwe@octave.org>
 
 	* data.cc (Freshape): Include mismatched dimensions in error message.

--- a/src/ov.cc
+++ b/src/ov.cc
@@ -1552,9 +1552,6 @@
                                              type_name (), "complex vector"));
 }
 
-// FIXME: This is a good place for pre-storage hooks, but the functions should
-// probably be named differently. These functions will be called
-
 octave_value 
 octave_value::storable_value (void) const
 {

--- a/src/ov.h
+++ b/src/ov.h
@@ -852,11 +852,14 @@
   void maybe_economize (void)
     { rep->maybe_economize (); }
 
-  // Make a copy suitable for storing.
+  // The following two hook conversions are called on any octave_value prior to
+  // storing it to a "permanent" location, like a named variable, a cell or a
+  // struct component, or a return value of a function. 
 
   octave_value storable_value (void) const;
 
-  // Ditto, but in place.
+  // Ditto, but in place, i.e. equivalent to *this = this->storable_value (),
+  // but possibly more efficient.
 
   void make_storable_value (void);