Update docs on DAP specs and DA specs

docs/deviceAttachmentPipelineSpec.md

@@ -2,11 +2,19 @@
 
 ## DAP Specs vs DA Specs:
 
-**DAP (Device Attachment Pipeline) specs** are human-readable DSL specifications that describe a pipeline of steps to connect a particular device role on a particular device-identifier to Salmanoff. This document describes the DAP specification format.
+**DAP (Device Attachment Pipeline) specs** are human-readable DSL
+specifications that describe a pipeline of steps to connect a particular
+device role on a particular device-identifier to Salmanoff. This document
+describes the DAP specification format.
 
-**DA (Device Attachment) specs** are compiled binary structs used internally by SMO after DAP specs have been parsed into binary format. DA specs are the internal representation that the system actually uses.
+**DA (Device Attachment) specs** are compiled binary structs used internally
+by SMO after DAP specs have been parsed into binary format. DA specs are the
+internal representation that the system actually uses.
 
-**Multiple Input Formats**: DAP specs can be parsed from multiple human-readable formats. For example, we intend to eventually extend ROS's URDF XML format to specify device attachment specs (URDFDA specs), which would also get compiled into the same DA spec binary format.
+**Multiple Input Formats**: DAP specs can be parsed from multiple
+human-readable formats. For example, we intend to eventually extend ROS's
+URDF XML format to specify device attachment specs (URDFDA specs), which
+would also get compiled into the same DA spec binary format.
 
 ## Attaching sensors:
 
@@ -34,7 +42,8 @@ sensor-type|dev-identifier|stim-iface-api|stim-buff-api(api-params)|provider(pro
   (extrospector), or '`+adev`' (actuator).
 * `dev-identifier` is a user-defined name for this specific device instance.
   This represents a logical device that can be accessed through multiple
-  providers and may expose multiple stim features.
+  providers and may expose multiple stim features. In a sense it's like a
+  sense organ or sense modality.
 * `stim-iface-api` is the name of the StimIface library that should be used to
   process the data from the stim buffer. This replaces the previous implexor
   concept.
@@ -44,7 +53,8 @@ sensor-type|dev-identifier|stim-iface-api|stim-buff-api(api-params)|provider(pro
   `api-params` in parentheses may be omitted, in which case the parentheses
   will be empty, but the parentheses must always be written out.
 * `provider` may be a userspace daemon or an OS kernel that provides access to
-  the device's stim buffers via the `stim-buff-api`. The `provider-params` in
+  the device's I/O functionality; and thereby allows the `stim-buff-api` to
+  construct and present a stim-buffer to Salmanoff. The `provider-params` in
   parentheses may be omitted, in which case the parentheses will be empty, but
   the parentheses must always be written out.
 * `dev-selector` is the idiosyncratic label/name used by the `provider` to
@@ -64,37 +74,75 @@ Each parameter must be in one of these forms:
 * key=
 * key
 
+### Important Note on `stim-buff-api-params`:
+
+The `stim-buff-api-params` should **never** include options related to the
+stim buffer's type or format. The `stim-buff-api` must read and infer such
+configuration details from the `stim-iface-api` portion of the DAP spec, and
+configure itself accordingly to enable connection by the specified
+stim-iface library in the way that it has been configured.
+
+`stim-buff-api-params` are for options that are:
+- Device-specific (not modality-wide)
+- Specific to this particular stim-feature as provided by this device
+- Configuration parameters needed by the stim-buff-api to properly interface
+  with the device
+
+Examples of appropriate `stim-buff-api-params`:
+- Buffer size settings
+- Device-specific communication parameters
+- Hardware-specific configuration options
+- Connection timeouts or retry settings
+
+Examples of **inappropriate** `stim-buff-api-params`:
+- Data format specifications (should be inferred from stim-iface-api)
+- Color space settings (should be determined by the stim-iface library)
+- Processing algorithm parameters (belong to the stim-iface library)
+
 ## Logical View and Multiple Access Patterns:
 
 ### Single Device, Multiple Providers:
 
-A single `dev-identifier` can unite several `dev-selectors` from multiple providers.
-For example, a sound card device `soundcard0` could be accessed through:
+A single `dev-identifier` can unite several `dev-selectors` from multiple
+providers. For example, a sound card device `soundcard0` could be accessed
+through:
 
-* `ident: soundcard0, provider: alsa` - Provides access to the card via ALSA API for audio output
-* `ident: soundcard0, provider: linux-driver-direct-file-ops` - Provides direct connection to Linux driver via read/write posix FD calls for beeper sound output  
-* `ident: soundcard0, provider: alsa` - Provides access to the card via ALSA for microphone input
+* `ident: soundcard0, provider: alsa` - Provides access to the card via ALSA
+  API for audio output
+* `ident: soundcard0, provider: linux-driver-direct-file-ops` - Provides direct
+  connection to Linux driver via read/write posix FD calls for beeper sound
+  output
+* `ident: soundcard0, provider: alsa` - Provides access to the card via ALSA
+  for microphone input
 
-So a single physical device is accessed via multiple providers, each with different selectors.
+So a single physical device is accessed via multiple providers, each with
+different selectors.
 
 ### Single Device, Same Provider, Different Stim-Buff-APIs:
 
-A device could have different `stim-buff-apis`, possibly provided by different shared libraries:
+A device could have different `stim-buff-apis`, possibly provided by different
+shared libraries:
 
-* `ident: soundcard0, provider: alsa, stim-buff-api: alsa-audio` - For audio output
-* `ident: soundcard0, provider: alsa, stim-buff-api: alsa-mic` - For microphone input
+* `ident: soundcard0, provider: alsa, stim-buff-api: alsa-audio` - For audio
+  output
+* `ident: soundcard0, provider: alsa, stim-buff-api: alsa-mic` - For microphone
+  input
 
-Different stim-buff-apis may be packaged into the same shared library, or multiple libraries may dlopen a common library behind the scenes.
+Different stim-buff-apis may be packaged into the same shared library, or
+multiple libraries may dlopen a common library behind the scenes.
 
 ### Stim Features and Buffers:
 
-Logically, a `dev-identifier` represents a sense modality. Each device can export multiple stim features. For example, an eye can export:
+Logically, a `dev-identifier` represents a sense modality. Each device can
+export multiple stim features. For example, an eye can export:
 - Color data
-- Light intensity data  
+- Light intensity data
 - Thermal heat data
 - Pain input data
 
-Each stim feature is exposed as a stim buffer, provided by a `stim-buff-api`. Stim-buff-apis rely upon providers to implement the device-specific operations required to effectuate the stim-buff controls.
+Each stim feature is exposed as a stim buffer, provided by a `stim-buff-api`.
+Stim-buff-apis rely upon providers to implement the device-specific operations
+required to effectuate the stim-buff controls.
 
 ## Examples: