From 2ee6d3bc9178df572fc3227ecb1c005ba3fd6b95 Mon Sep 17 00:00:00 2001 From: Arlie Capps Date: Tue, 1 Oct 2019 10:00:13 -0700 Subject: [PATCH 1/2] Clarify comments on the root Group's name --- src/axom/sidre/core/DataStore.hpp | 5 +++-- src/axom/sidre/core/Group.hpp | 6 +++++- src/axom/sidre/docs/sphinx/datastore.rst | 2 +- src/axom/sidre/docs/sphinx/group.rst | 18 +++++++++++------- 4 files changed, 20 insertions(+), 11 deletions(-) diff --git a/src/axom/sidre/core/DataStore.hpp b/src/axom/sidre/core/DataStore.hpp index e5a40a10ce..60ab08f75c 100644 --- a/src/axom/sidre/core/DataStore.hpp +++ b/src/axom/sidre/core/DataStore.hpp @@ -45,8 +45,9 @@ template 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 { diff --git a/src/axom/sidre/core/Group.hpp b/src/axom/sidre/core/Group.hpp index 4115e7de13..b286f8e23c 100644 --- a/src/axom/sidre/core/Group.hpp +++ b/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); diff --git a/src/axom/sidre/docs/sphinx/datastore.rst b/src/axom/sidre/docs/sphinx/datastore.rst index 41264ff561..08c7ef9a9d 100644 --- a/src/axom/sidre/docs/sphinx/datastore.rst +++ b/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 diff --git a/src/axom/sidre/docs/sphinx/group.rst b/src/axom/sidre/docs/sphinx/group.rst index fa34d3d921..3e3f86dc5d 100644 --- a/src/axom/sidre/docs/sphinx/group.rst +++ b/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 @@ -50,7 +51,9 @@ 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 +Views take a string with *path syntax*, where parent and child Group names +are joined with the path separator character (usually '/'). +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,15 @@ 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 or to + a string containing the path separator character. * 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 From 235cd8c6f1b092fc1ffe8fe189e8b63ab2b7eea3 Mon Sep 17 00:00:00 2001 From: Arlie Capps Date: Tue, 8 Oct 2019 07:29:20 -0700 Subject: [PATCH 2/2] responded to reviewer comments --- src/axom/sidre/docs/sphinx/buffer.rst | 4 ++-- src/axom/sidre/docs/sphinx/group.rst | 9 +++++---- src/axom/sidre/docs/sphinx/view.rst | 2 +- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/axom/sidre/docs/sphinx/buffer.rst b/src/axom/sidre/docs/sphinx/buffer.rst index e1de85dc7c..34185602d6 100644 --- a/src/axom/sidre/docs/sphinx/buffer.rst +++ b/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. diff --git a/src/axom/sidre/docs/sphinx/group.rst b/src/axom/sidre/docs/sphinx/group.rst index 3e3f86dc5d..a0cfb33da8 100644 --- a/src/axom/sidre/docs/sphinx/group.rst +++ b/src/axom/sidre/docs/sphinx/group.rst @@ -50,9 +50,9 @@ 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 +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 (usually '/'). +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 @@ -92,8 +92,9 @@ 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. A Group cannot be renamed to the empty string or to - a string containing the path separator character. + * 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). * Destroy all child groups in a Group. diff --git a/src/axom/sidre/docs/sphinx/view.rst b/src/axom/sidre/docs/sphinx/view.rst index 328abca498..537fffe798 100644 --- a/src/axom/sidre/docs/sphinx/view.rst +++ b/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