Apply suggestions from code review

Co-authored-by: Oliver Ruebel <[email protected]>

docs/pages/userdocs/workflow.dox

@@ -8,66 +8,73 @@
  * For users wanting to integrate NWB with a particular data acquisition software, here
  * we outline the steps for a single recording from file creation to saving.
  *
- * 1. Create the I/O object.
- * 2. Create the `RecordingContainers` object. 
- * 3. Create the `NWBFile` object.
- * 4. Create datasets and add to RecordingContainers.
+ * 1. Create the I/O object (e.g,.  \ref AQNWB::HDF5::HDF5IO "HDF5IO") used for writing data to the file on disk.
+ * 2. Create the \ref AQNWB::NWB::RecordingContainers "RecordingContainers" object used for managing \ref AQNWB::NWB::Container "Container" objects for storing recordings.
+ * 3. Create the \ref AQNWB::NWB::NWBFile "NWBFile" object used for managing and creating NWB file contents.
+ * 4. Create the \ref AQNWB::NWB::Container "Container" objects (e.g., \ref AQNWB::NWB::ElectricalSeries "ElectricalSeries") used for recording and add them to the \ref AQNWB::NWB::RecordingContainers "RecordingContainers".
  * 5. Start the recording.
  * 6. Write data.
- * 7. Stop the recording and close the NWBFile.
+ * 7. Stop the recording and close the \ref AQNWB::NWB::NWBFile "NWBFile".
  * 
  * Below, we walk through these steps in more detail.
  * 
  * 
  * \subsection create_io 1. Create the I/O object.
  * 
- * First, create an I/O object. We provide a convenience method, `createIO`
+ * First, create an I/O object (e.g., \ref AQNWB::HDF5::HDF5IO "HDF5IO") used for writing data to the file.
+ * We provide a convenience method, \ref AQNWB::createIO "createIO"
  * to create this object using one of our supported backends. For more fine-grained
  * control of different backend parameters, you can create your own `std::shared_ptr` 
- * using any of the derived BaseIO classes.
+ * using any of the derived \ref AQNWB::BaseIO "BaseIO" classes.
  * 
  * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_io_snippet
  *
  *
  * \subsection create_recording_container 2. Create the RecordingContainer object.
  * 
- * Next, create a RecordingContainer object to manage the different datasets 
+ * Next, create a \ref AQNWB::NWB::RecordingContainers "RecordingContainers"  object to manage the different \ref AQNWB::NWB::Container "Container" objects with the datasets
  * that you would like to write data to.
  * 
  * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_recording_containers_snippet
  * 
  *
  * \subsection create_nwbfile 3. Create the NWBFile
  * 
- * Next, constructs the `NWBFile` object, using the I/O object as an input. 
+ * Next, constructs the \ref AQNWB::NWB::NWBFile "NWBFile"  object, using the I/O object as an input. 
  * Then, initialize the object to create the basic file structure of the NWBFile.
  *
  * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_nwbfile_snippet
  *
  * 
  * \subsection create_datasets 4. Create datasets and add to RecordingContainers.
  *
- * Next, create the different data types (e.g. `ElectricalSeries`, other `TimeSeries`)
- * that you would like to write data into. After creation, these objects are moved
- * to the RecordingContainers object so that it can manage access and data writing
+ * Next, create the different data types (e.g. \ref AQNWB::NWB::ElectricalSeries "ElectricalSeries" or other AQNWB::NWB::TimeSeries "TimeSeries")
+ * that you would like to write data into. After creation, these objects are added
+ * to the  \ref AQNWB::NWB::RecordingContainers "RecordingContainers"  object so that it can manage access and data writing
  * during the recording process. 
  * 
  * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_datasets_snippet
  *
  *
  * \subsection start_recording 5. Start the recording.
  *
- * Then, start the recording process with a call to the I/O object. By default for
- * HDF5 files, this will enable SWMR mode and no additional datasets or groups can be added
- * to the file unless it is closed and reopened.
+ * Then, start the recording process with a call to the ``startRecording`` function of the I/O object. 
+ *
+ *  \note 
+ * When using \ref AQNWB::HDF5::HDF5IO "HDF5IO" for writing to HDF5, calling 
+ * \ref AQNWB::HDF5::HDF5IO::startRecording "startRecording" will by default enable
+ * \ref hdf5io_swmr "SWMR mode" to ensure file integrity and support concurrent read. 
+ * As a result, no additional datasets or groups can be added to the file once a recording
+ * has been started unless the file is is closed and reopened.
  *
  * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_start_snippet
  *
  * 
  * \subsection write_data 6. Write data.
  *
- * During the recording process, use the RecordingContainers as an interface
- * to access the various datasets and write blocks of data to the file. 
+ * During the recording process, use the \ref AQNWB::NWB::RecordingContainers "RecordingContainers"  as an interface
+ * to access the various  \ref AQNWB::NWB::Container "Container" object and corresponding 
+ * datasets and write blocks of data to the file. 
  * 
  * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_write_snippet
  *