Merge pull request #111 from LLNL/bugfix/capps2/sidre-naming-document…

…ation

Root group name documentation

src/axom/sidre/core/DataStore.hpp

@@ -45,8 +45,9 @@ template <typename TYPE> class MapCollection;
  *        Buffer objects.
  *
  * It maintains a collection of Buffer objects and owns the "root"
- * Group, called "/". A Group hierarchy (a tree) is created by
- * creating child Groups of Groups.
+ * Group.  The initial name of the root Group is the empty string: a
+ * code uses the getRoot() method to retrieve the root Group.  A Group
+ * hierarchy (a tree) is created by creating child Groups of Groups.
  */
 class DataStore
 {

src/axom/sidre/core/Group.hpp

@@ -1352,9 +1352,13 @@ class Group
    * identical to a name that is already held by the parent for another
    * Group or View object.
    *
+   * It is possible to rename the root Group, but a code cannot
+   * subsequently rename root Group back to its original empty string
+   * name.
+   *
    * \param new_name    The new name for this group.
    *
-   * /return            Success or failure of rename.
+   * \return            Success or failure of rename.
    */
   bool rename(const std::string& new_name);
 

src/axom/sidre/docs/sphinx/buffer.rst

@@ -43,8 +43,8 @@ The Buffer interface includes the following operations:
  * Copy a given number of bytes of data from a given pointer to a Buffer
    allocation.
  * Get data held by a Buffer as a pointer or conduit::Node::Value type.
- * Get information about Buffer data: type, number of elements, total number 
-   of bytes, number of bytes per element, etc.
+ * Get information about data held by a Buffer: type, number of elements,
+   total number of bytes, number of bytes per element, etc.
  * Retrieve the number of Views the Buffer is attached to.
  * Copy Buffer description and its data to/from a conduit::Node.
 

src/axom/sidre/docs/sphinx/datastore.rst

@@ -11,7 +11,7 @@ DataStore
 
 A Sidre DataStore object provides the main access point for Sidre contents,
 including the data managed by Sidre. In particular, a DataStore maintains the 
-group at the root of the Sidre group hierarchy (named "/"), a collection of 
+group at the root of the Sidre group hierarchy, a collection of
 Buffer objects, and a collection of Attribute objects. Generally, the first 
 thing a Sidre user does is create a DataStore; this operation also creates 
 the root group. Apart from providing access to the root group, a DataStore 

src/axom/sidre/docs/sphinx/group.rst

@@ -13,8 +13,9 @@ Sidre Group objects are used to define a tree-like hierarchical organization
 for application data, such as meshes and fields used in a simulation. Each 
 Group has a name and one parent Group (except for the root Group) and contains
 zero or more child Groups and zero or more Views. A Sidre DataStore has 
-exactly one root Group (named "/"), which is created when the DataStore object
-is created. See :ref:`datastore-label` for more information.
+exactly one root Group which is created when the DataStore object
+is created. The root Group's name is initially the empty string.
+See :ref:`datastore-label` for more information.
 
 A Group hierarchy is constructed by creating Groups that are children of the
 root Group, children of those Groups, and so on. All Groups in a subtree 
@@ -49,8 +50,10 @@ the data is shared by the original and new View.
 
 .. note:: View copy operations perform **shallow** copies of the View data.
 
-Some methods for for creating, destroying, querying, and retrieving Groups and 
-Views take a string with *path syntax*, while others take the name of an
+Some methods for creating, destroying, querying, and retrieving Groups and
+Views take a string with *path syntax*, where parent and child Group names
+are joined with the path separator character, '/'.
+Other methods take the name of an
 immediate child of a Group. Methods that require the name of a direct child 
 are marked with 'Child' in their name, such as ``hasChildView()`` and 
 ``hasChildGroup()``. When a path string is passed to a method that accepts 
@@ -84,14 +87,16 @@ Group objects.
             become invalid. This is analogous to iterator invalidation for
             containers when the container contents change.
 
-Create and Destroy Groups
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create, Modify, and Destroy Groups
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
  * Create a child Group given a name (child) or path (other descendant). 
    If a path is given, intermediate Groups in path are created, if needed. 
- * Rename a Group.
+ * Rename a Group.  A Group cannot be renamed to the empty string, to
+   a string containing the path separator character, or to the name of
+   another Group or View owned by the same parent.
  * Destroy a descendant Group with given id (child), or name/path (child or 
-   other descendant)
+   other descendant).
  * Destroy all child groups in a Group.
 
 .. note:: When a Group is destroyed, all Groups and Views in the subtree 

src/axom/sidre/docs/sphinx/view.rst

@@ -34,7 +34,7 @@ pointer in one of four ways described below. In that case, a View data
 description includes: a data type, a length (number of elements), an offset 
 and a stride (based on the pointer address and data type). 
 
-  * A View can describe (a subset of) data owned by an pre-existing Buffer. 
+  * A View can describe (a subset of) data owned by a pre-existing Buffer.
     In this case, the Buffer is manually *attached* to the View and the
     View's data description is applied to the Buffer data. Buffer data can be 
     (re)allocated or deallocated by the View if and only if it is the only