Update ExternalResources doc strings (#48)

hdmf-dev · Dec 2, 2020 · 8b2324d · 8b2324d
1 parent cca2846
commit 8b2324d
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 13 deletions.
diff --git a/common/resources.yaml b/common/resources.yaml
@@ -1,11 +1,13 @@
+# hdmf-schema-language=2.0.2
 groups:
  - data_type_def: ExternalResources
    data_type_inc: Container
-   doc: A pair of tables for tracking external resource references in a file
+   doc: "A set of four tables for tracking external resource references in a file. NOTE: this data type is in beta
+     testing and is subject to change in a later version."
    datasets:
     - data_type_inc: Data
       name: keys
-      doc: A table for storing user terms that are used to refer to external resources
+      doc: A table for storing user terms that are used to refer to external resources.
       dtype:
        - name: key_name
          dtype: text
@@ -17,17 +19,17 @@ groups:
 
     - data_type_inc: Data
       name: resources
-      doc: A table for mapping user terms (i.e. keys) to resource entities
+      doc: A table for mapping user terms (i.e., keys) to resource entities.
       dtype:
        - name: keytable_idx
          dtype: uint
-         doc: Foreign reference to the 'keys' table - the index to the key in the 'keys' table.
+         doc: The index to the key in the 'keys' table.
        - name: resource_name
          dtype: text
-         doc: The name of the online resource (i.e. website, database) that has the entity
+         doc: The name of the online resource (e.g., website, database) that has the entity.
        - name: resource_id
          dtype: text
-         doc: The unique identifier for the resource entity at the resource
+         doc: The unique identifier for the resource entity at the resource.
        - name: uri
          dtype: text
          doc: The URI for the resource entity this reference applies to. This can be an empty string.
@@ -38,29 +40,30 @@ groups:
 
     - data_type_inc: Data
       name: objects
-      doc: A table for identifying which objects in a file contain references to external resources
+      doc: A table for identifying which objects in a file contain references to external resources.
       dtype:
        - name: object_id
          dtype: text
-         doc: The UUID for the object
+         doc: The UUID for the object.
        - name: field
          dtype: text
-         doc: The field of the object. This can be an empty string if the object is a dataset and the field is the dataset values.
+         doc: The field of the object. This can be an empty string if the object is a dataset and the field is the
+           dataset values.
       dims:
       - num_rows
       shape:
       - null
 
     - data_type_inc: Data
       name: object_keys
-      doc: A table for identifying which objects use which keys
+      doc: A table for identifying which objects use which keys.
       dtype:
        - name: objecttable_idx
          dtype: uint
-         doc: The index to the 'objects' table for the object that holds the key
+         doc: The index to the 'objects' table for the object that holds the key.
        - name: keytable_idx
          dtype: uint
-         doc: The index to the 'keys' table for the key
+         doc: The index to the 'keys' table for the key.
       dims:
       - num_rows
       shape:

diff --git a/docs/source/format_release_notes.rst b/docs/source/format_release_notes.rst
@@ -4,7 +4,8 @@ hdmf-common Release Notes
 1.3.0 (Upcoming)
 -------------------------
 
-- Add data type ``ExternalResources`` for storing ontology information / external resource references.
+- Add data type ``ExternalResources`` for storing ontology information / external resource references. NOTE: this
+  data type is in beta testing and is subject to change in a later version.
 - Changed dtype for datasets within ``CSRMatrix`` from 'int' to 'uint'. Negative values do not make sense for these
   datasets.