Add reference documentation for public API

Author: glopesdev

harp/io.py

@@ -6,11 +6,13 @@
 import numpy as np
 import pandas as pd
 
-"""The reference epoch for UTC harp time."""
 REFERENCE_EPOCH = datetime(1904, 1, 1)
+"""The reference epoch for UTC harp time."""
 
 
 class MessageType(IntEnum):
+    """Specifies the type of a Harp message."""
+
     NA = 0
     READ = 1
     WRITE = 2
@@ -41,22 +43,33 @@ def read(
     epoch: Optional[datetime] = None,
     keep_type: bool = False,
 ):
-    """
-    Read single-register Harp data from the specified file.
-
-    :param file: Open file object or filename containing binary data from
-      a single device register.
-    :param address: Expected register address. If specified, the address of
-      the first message in the file is used for validation.
-    :param dtype: Expected data type of the register payload. If specified, the
-      payload type of the first message in the file is used for validation.
-    :param length: Expected number of elements in register payload. If specified,
-      the payload length of the first message in the file is used for validation.
-    :param columns: The optional column labels to use for the data values.
-    :param epoch: Reference datetime at which time zero begins. If specified,
-      the result data frame will have a datetime index.
-    :param keep_type: Specifies whether to include a column with the message type.
-    :return: A pandas data frame containing message data, sorted by time.
+    """Read single-register Harp data from the specified file.
+
+    Parameters
+    ----------
+    file
+        Open file object or filename containing binary data from
+        a single device register.
+    address
+        Expected register address. If specified, the address of
+        the first message in the file is used for validation.
+    dtype
+        Expected data type of the register payload. If specified, the
+        payload type of the first message in the file is used for validation.
+    length
+        Expected number of elements in register payload. If specified, the
+        payload length of the first message in the file is used for validation.
+    columns
+        The optional column labels to use for the data values.
+    epoch
+        Reference datetime at which time zero begins. If specified,
+        the result data frame will have a datetime index.
+    keep_type
+        Specifies whether to include a column with the message type.
+
+    Returns
+    -------
+        A pandas data frame containing message data, sorted by time.
     """
     data = np.fromfile(file, dtype=np.uint8)
     if len(data) == 0:

harp/reader.py

@@ -213,6 +213,30 @@ def create_reader(
     epoch: Optional[datetime] = None,
     keep_type: bool = False,
 ):
+    """Creates a device reader object from the specified dataset or schema.
+    
+    Parameters
+    ----------
+    device
+        A path to the device schema, dataset folder, or parsed device schema object
+        describing the device.
+    include_common_registers
+        Specifies whether to include the set of Harp common registers in the
+        parsed device schema object. If a parsed device schema object is provided,
+        this parameter is ignored.
+    epoch
+        The default reference datetime at which time zero begins. If specified,
+        the data frames returned by each register reader will have a datetime index.
+    keep_type
+        Specifies whether to include a column with the message type by default.
+
+    Returns
+    -------
+        A device reader object which can be used to read binary data for each
+        register or to access metadata about each register. Individual registers
+        can be accessed using dot notation using the name of the register as the
+        key.
+    """
     if isinstance(device, Model):
         base_path = Path(device.device)
     else:

harp/schema.py

@@ -14,6 +14,22 @@ def _read_common_registers() -> Registers:
 def read_schema(
     file: Union[str, PathLike, TextIO], include_common_registers: bool = True
 ) -> Model:
+    """Read and parse a device schema from the specified file.
+    
+    Parameters
+    ----------
+    file
+        Open file object or filename containing a YAML text stream describing
+        a device schema.
+    include_common_registers
+        Specifies whether to include the set of Harp common registers in the
+        returned device schema object.
+
+    Returns
+    -------
+        A Pydantic model object representing the Harp device schema.
+    """
+
     if isinstance(file, (str, PathLike)):
         with open(file) as fileIO:
             return read_schema(fileIO)