[Bf-blender-cvs] [33949188a77] functions: add some comments

[Jacques Lucke]

Commit: 33949188a778c4f20aadaf94627d662e62554aae
Author: Jacques Lucke
Date:   Wed Aug 21 17:57:42 2019 +0200
Branches: functions
https://developer.blender.org/rB33949188a778c4f20aadaf94627d662e62554aae

add some comments

===================================================================

M	source/blender/blenlib/BLI_allocator.hpp
M	source/blender/blenlib/BLI_array.hpp
M	source/blender/blenlib/BLI_array_ref.hpp

===================================================================

diff --git a/source/blender/blenlib/BLI_allocator.hpp b/source/blender/blenlib/BLI_allocator.hpp
index 4da905e9e63..24b9c779942 100644
--- a/source/blender/blenlib/BLI_allocator.hpp
+++ b/source/blender/blenlib/BLI_allocator.hpp
@@ -1,3 +1,32 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/** \file
+ * \ingroup bli
+ *
+ * This file offers a couple of memory allocators that can be used with containers such as Vector
+ * and Map. Note that these allocators are not designed to work with standard containers like
+ * std::vector.
+ *
+ * Also see http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html for why the standard
+ * allocators are not a good fit applications like Blender. The current implementations in this
+ * file are fairly simple still, more complexity can be added when necessary. For now they do their
+ * job good enough.
+ */
+
 #pragma once
 
 #include <stdlib.h>
diff --git a/source/blender/blenlib/BLI_array.hpp b/source/blender/blenlib/BLI_array.hpp
index 4bd9b0e900f..99fcc9a961e 100644
--- a/source/blender/blenlib/BLI_array.hpp
+++ b/source/blender/blenlib/BLI_array.hpp
@@ -1,3 +1,26 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/** \file
+ * \ingroup bli
+ *
+ * This is a container that contains a fixed size array. Note however, the size of the array is not
+ * a template argument. Instead it can be specified at the construction time.
+ */
+
 #pragma once
 
 #include "BLI_utildefines.h"
diff --git a/source/blender/blenlib/BLI_array_ref.hpp b/source/blender/blenlib/BLI_array_ref.hpp
index fd8f6468f7b..e3d5a3a89ae 100644
--- a/source/blender/blenlib/BLI_array_ref.hpp
+++ b/source/blender/blenlib/BLI_array_ref.hpp
@@ -17,12 +17,19 @@
 /** \file
  * \ingroup bli
  *
- * An ArrayRef references some memory buffer owned
- * by someone else. If possible, functions should take
- * an ArrayRef as input. This allows passing on different
- * kinds of class types without doing unnecessary conversions.
+ * This classes offer a convenient way to work with continuous chunks of memory of a certain type.
+ * We differentiate ArrayRef and MutableArrayRef. The elements in the former are const while the
+ * elements in the other are not.
  *
- * ArrayRef instances should be passed by value.
+ * Passing array references as parameters has multiple benefits:
+ *   - Less templates are used since the function does not have to work with different
+ *     container types.
+ *   - It encourages an Struct-of-Arrays data layout which is often benefitial when
+ *     writing high performance code. Also it makes it easier to reuse code.
+ *   - Array references offer convenient ways of slicing and other operations.
+ *
+ * The instrances of ArrayRef and MutableArrayRef are very small and should be passed by value.
+ * Since array references do not own any memory, it is generally not save to store them.
  */
 
 #pragma once
@@ -38,6 +45,9 @@
 
 namespace BLI {
 
+/**
+ * References an array of data. The elements in the array should not be changed.
+ */
 template<typename T> class ArrayRef {
  private:
   const T *m_start = nullptr;
@@ -136,11 +146,6 @@ template<typename T> class ArrayRef {
     return m_start[index];
   }
 
-  const T *data() const
-  {
-    return m_start;
-  }
-
   /**
    * Return the number of elements in the referenced array.
    */
@@ -252,6 +257,9 @@ template<typename T> class ArrayRef {
   }
 };
 
+/**
+ * Mostly the same as ArrayRef, except that one can change the array elements via this reference.
+ */
 template<typename T> class MutableArrayRef {
  private:
   T *m_start;
@@ -279,14 +287,12 @@ template<typename T> class MutableArrayRef {
 
   operator ArrayRef<T>()
   {
-    return ArrayRef<T>(this->data(), this->size());
-  }
-
-  T *data() const
-  {
-    return m_start;
+    return ArrayRef<T>(m_start, m_size);
   }
 
+  /**
+   * Get the number of elements in the array.
+   */
   uint size() const
   {
     return m_size;