Merge pull request #25 from iluvcapra/maint-docs

More Documentation Improvements: cues

README.md

@@ -24,19 +24,22 @@ source for all WAVE file metadata.
 * [iXML][ixml] production recorder metadata, including project, scene, and 
   take tags, recorder notes and file family information.
   * iXML `STEINBERG` sound library attributes.
-* Wave embedded cue markers, cue marker labels, notes and timed ranges as used
+* Wave embedded [cue markers][cues], cue marker labels, notes and timed ranges as used
   by Zoom, iZotope RX, etc.
 * Most of the common [RIFF INFO][info-tags] metadata fields.
-* The __wav format__ is also parsed, so you can access the basic sample rate 
+* The [wav format][format] is also parsed, so you can access the basic sample rate 
   and channel count information.
 
-[bext]: https://wavinfo.readthedocs.io/en/latest/scopes/bext.html
-[smpte_330m2011]: https://wavinfo.readthedocs.io/en/latest/scopes/bext.html#wavinfo.wave_bext_reader.WavBextReader.umid
-[adm]: https://wavinfo.readthedocs.io/en/latest/scopes/adm.html
-[ebu3285s6]: https://wavinfo.readthedocs.io/en/latest/scopes/dolby.html
-[ixml]: https://wavinfo.readthedocs.io/en/latest/scopes/ixml.html
-[info-tags]: https://wavinfo.readthedocs.io/en/latest/scopes/info.html
-[eburf64]: https://tech.ebu.ch/docs/tech/tech3306v1_1.pdf
+
+[format]:https://wavinfo.readthedocs.io/en/latest/classes.html#wavinfo.wave_reader.WavAudioFormat
+[cues]:https://wavinfo.readthedocs.io/en/latest/scopes/cue.html
+[bext]:https://wavinfo.readthedocs.io/en/latest/scopes/bext.html
+[smpte_330m2011]:https://wavinfo.readthedocs.io/en/latest/scopes/bext.html#wavinfo.wave_bext_reader.WavBextReader.umid
+[adm]:https://wavinfo.readthedocs.io/en/latest/scopes/adm.html
+[ebu3285s6]:https://wavinfo.readthedocs.io/en/latest/scopes/dolby.html
+[ixml]:https://wavinfo.readthedocs.io/en/latest/scopes/ixml.html
+[info-tags]:https://wavinfo.readthedocs.io/en/latest/scopes/info.html
+[eburf64]:https://tech.ebu.ch/docs/tech/tech3306v1_1.pdf
 
 
 ## How To Use

docs/source/scopes/cue.rst

@@ -29,3 +29,12 @@ Class Reference
 
 .. autoclass:: wavinfo.wave_cues_reader.WavCuesReader
    :members:
+
+.. autoclass:: wavinfo.wave_cues_reader.CueEntry
+   :members:
+
+.. autoclass:: wavinfo.wave_cues_reader.LabelEntry
+   :members:
+
+.. autoclass:: wavinfo.wave_cues_reader.NoteEntry
+   :members:

wavinfo/wave_cues_reader.py

@@ -98,7 +98,14 @@
 
 
 class CueEntry(NamedTuple):
+    """
+    A ``cue`` element structure.
+    """
+    #: Cue "name" or id number 
     name: int
+    #: Cue position, as a frame count in the play order of the WAVE file. In 
+    #: principle this can be affected by playlists and ``wavl`` chunk 
+    #: placement.
     position: int
     chunk_id: bytes
     chunk_start: int
@@ -114,7 +121,8 @@ def format_size(cls) -> int:
     @classmethod
     def read(cls, data: bytes) -> 'CueEntry':
         assert len(data) == cls.format_size(), \
-            f"cue data size incorrect, expected {calcsize(cls.Format)} found {len(data)}"
+            (f"cue data size incorrect, expected {calcsize(cls.Format)}" 
+             "found {len(data)}")
 
         parsed = unpack(cls.Format, data)
 
@@ -124,6 +132,9 @@ def read(cls, data: bytes) -> 'CueEntry':
 
 
 class LabelEntry(NamedTuple):
+    """
+    A ``labl`` structure.
+    """
     name: int
     text: str
 
@@ -137,6 +148,9 @@ def read(cls, data: bytes, encoding: str):
 
 
 class RangeLabel(NamedTuple):
+    """
+    A ``ltxt`` structure.
+    """
     name: int
     length: int
     purpose: str
@@ -163,9 +177,17 @@ def read(cls, data: bytes, fallback_encoding: str):
 
 @dataclass
 class WavCuesReader:
+
+    #: Every ``cue`` entry in the file
     cues: List[CueEntry]
+
+    #: Every ``labl`` in the file
     labels: List[LabelEntry]
+
+    #: Every ``ltxt`` in the file
     ranges: List[RangeLabel]
+
+    #: Every ``note`` in the file
     notes: List[NoteEntry]
 
     @classmethod