ENH: Added comments.

include/FArray.hh

@@ -13,9 +13,12 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-//  Dynamic, self adjusting floating point array
-//
+// .NAME vlFloatArray - dynamic, self adjusting floating point array
+// .SECTION Description
+// vlFloatArray is an array of floating point numbers. It provides methods
+// for insertion and retrieval of floating point values, and will 
+// automatically resize itself to hold new data.
+
 #ifndef __vlFloatArray_h
 #define __vlFloatArray_h
 
@@ -30,30 +33,27 @@ public:
   vlFloatArray(const int sz, const int ext=1000);
   vlFloatArray(const vlFloatArray& fa);
   ~vlFloatArray();
-  float GetValue(const int id) {return this->Array[id];};
-  float *GetPtr(const int id) {return this->Array + id;};
-  vlFloatArray &InsertValue(const int id, const float f)
-    {if ( id >= this->Size ) this->Resize(id);
-     this->Array[id] = f;
-     if ( id > this->MaxId ) this->MaxId = id;
-     return *this;
-    }
-  int InsertNextValue(const float f)
-    {this->InsertValue (++this->MaxId,f); return this->MaxId;};
+  virtual char *GetClassName() {return "vlFloatArray";};
+  void PrintSelf(ostream& os, vlIndent indent);
+
+  // access/insertion methods
+  float GetValue(const int id);
+  float *GetPtr(const int id);
+  vlFloatArray &InsertValue(const int id, const float f);
+  int InsertNextValue(const float f);
+
+  // special operators
   vlFloatArray &operator=(const vlFloatArray& fa);
   vlFloatArray &operator+=(const vlFloatArray& fa);
   void operator+=(const float f) {this->InsertNextValue(f);};
-  // operator[] can be used on both left and right side of expression;
-  // Note: if used on lh side, user's responsibility to do range checking
-  float& operator[](const int i)
-    {if (i > this->MaxId) this->MaxId = i; return this->Array[i];};
-  void Squeeze() {this->Resize (this->MaxId+1);};
-  int GetSize() {return this->Size;};
-  int GetMaxId() {return this->MaxId;};
-  float *GetArray() {return this->Array;};
-  void Reset() {this->MaxId = -1;};
-  virtual char *GetClassName() {return "vlFloatArray";};
-  void PrintSelf(ostream& os, vlIndent indent);
+  float& operator[](const int i);
+
+  // miscellaneous methods
+  void Squeeze();
+  int GetSize();
+  int GetMaxId();
+  float *GetArray();
+  void Reset();
 
 private:
   float *Array;   // pointer to data
@@ -63,4 +63,61 @@ private:
   float *Resize(const int sz);  // function to resize data
 };
 
+// Description:
+// Get the data at a particular index.
+inline float vlFloatArray::GetValue(const int id) {return this->Array[id];};
+
+// Description:
+// Get the address of a particular data index.
+inline float *vlFloatArray::GetPtr(const int id) {return this->Array + id;};
+
+// Description:
+// Insert data at a specified position in the array.
+inline vlFloatArray& vlFloatArray::InsertValue(const int id, const float f)
+{
+  if ( id >= this->Size ) this->Resize(id);
+  this->Array[id] = f;
+  if ( id > this->MaxId ) this->MaxId = id;
+  return *this;
+}
+
+// Description:
+// Insert data at the end of the array. Return its location in the array.
+inline int vlFloatArray::InsertNextValue(const float f)
+{
+  this->InsertValue (++this->MaxId,f); 
+  return this->MaxId;
+}
+
+// Description:
+// Does insert or get (depending on location on lhs or rhs of statement). Does
+// not do automatic resizing - user's responsibility to range check.
+inline float& vlFloatArray::operator[](const int i)
+{
+  if (i > this->MaxId) this->MaxId = i; 
+  return this->Array[i];
+}
+
+// Description:
+// Resize object to just fit data requirement. Reclaims extra memory.
+inline void vlFloatArray::Squeeze() {this->Resize (this->MaxId+1);};
+
+// Description:
+// Get the allocated size of the object in terms of number of data items.
+inline int vlFloatArray::GetSize() {return this->Size;};
+
+// Description:
+// Returning the maximum index of data inserted so far.
+inline int vlFloatArray::GetMaxId() {return this->MaxId;};
+
+// Description:
+// Get the pointer to the array. Useful for interfacing to C or 
+// FORTRAN routines.
+inline float *vlFloatArray::GetArray() {return this->Array;};
+
+// Description:
+// Reuse the memory allocated by this object. Objects appears like
+// no data has been previously inserted.
+inline void vlFloatArray::Reset() {this->MaxId = -1;};
+
 #endif

src/FArray.cc

@@ -13,15 +13,10 @@ written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-//  Dynamic, self adjusting floating point array
-//
-//  Assumptions:
-//    - no bounds/range checking -> user responsibility
-//    - the Register/unRegister methods called only by container class
-//
 #include "FArray.hh"
 
+// Description:
+// Allocate memory for this array. Delete old storage if present.
 int vlFloatArray::Allocate(const int sz, const int ext)
 {
   if ( this->Array ) delete [] this->Array;
@@ -34,6 +29,8 @@ int vlFloatArray::Allocate(const int sz, const int ext)
   return 1;
 }
 
+// Description:
+// Release storage and reset array to initial state.
 void vlFloatArray::Initialize()
 {
   if ( this->Array != NULL )
@@ -45,6 +42,8 @@ void vlFloatArray::Initialize()
   this->MaxId = -1;
 }
 
+// Description:
+// 
 vlFloatArray::vlFloatArray(const int sz, const int ext)
 {
   this->Size = ( sz > 0 ? sz : 1);
@@ -58,6 +57,8 @@ vlFloatArray::~vlFloatArray()
   delete [] this->Array;
 }
 
+// Description:
+// Construct array from another array. Copy each element of other array.
 vlFloatArray::vlFloatArray(const vlFloatArray& fa)
 {
   int i;
@@ -72,6 +73,8 @@ vlFloatArray::vlFloatArray(const vlFloatArray& fa)
 
 }
 
+// Description:
+// Deep copy of another array.
 vlFloatArray& vlFloatArray::operator=(const vlFloatArray& fa)
 {
   int i;
@@ -91,9 +94,8 @@ vlFloatArray& vlFloatArray::operator=(const vlFloatArray& fa)
   return *this;
 }
 
-//
-// Copy on write if used by more than one object
-//
+// Description:
+// Append one array onto the end of this array.
 vlFloatArray& vlFloatArray::operator+=(const vlFloatArray& fa)
 {
   int i, sz;
@@ -122,8 +124,7 @@ void vlFloatArray::PrintSelf(ostream& os, vlIndent indent)
   }
 }
 
-//
-// Private function does "reallocate"
+// Protected function does "reallocate"
 //
 float *vlFloatArray::Resize(const int sz)
 {