[Documentation]: Improve docs around setting "name" for a neurodata_type

[rly]

What would you like changed or added to the documentation and why?

Related to hdmf-dev/hdmf#972

If a group spec contains group or dataset neurodata types and specifies a particular name for them, e.g.,

- neurodata_type_def: Task
  neurodata_type_inc: LabMetaData
  name: task
  doc: A group to store task-related general metadata. TODO When merged with core,
    this will no longer inherit from LabMetaData but from NWBContainer and be placed
    optionally in /general.
  groups:
  - name: event_types
    neurodata_type_inc: EventTypesTable
    doc: Table to store information about each task event type.
    quantity: '?'
  - name: ttl_types
    neurodata_type_inc: TtlTypesTable
    doc: Table to store information about each task TTL type.
    quantity: '?'

Then a common point of confusion when using the API is that the child neurodata type objects (e.g., EventTypesTable and TtlTypesTable) MUST be named the names specified in the schema (e.g., "event_types" and "ttl_types"). The objects can be created with any name and added to the parent object. If the extension creator auto-generated the class, then the class will set the __fields__ property for each of those fields correctly to contain {"required_name": ___ } which enforces that the child objects have the specified name. However, if the extension creator defines their own custom class, they may not know to do this, and a user may use the API to add a child with the wrong name to the parent. If the child is optional, then no error will be raised on write, and the data file will be missing the child object unbeknownst to the user. We should add a note about this in the documentation. And maybe also add a warning in the HDMF objectmapper whenever a child object with a neurodata type is found within a parent and it is not mapped to anything in the schema.

Do you have any interest in helping write or edit the documentation?

Yes.

Code of Conduct

• I agree to follow this project's Code of Conduct
• Have you checked the Contributing document?
• Have you ensured this change was not already requested?