Add more comments

Author: Jayson-Fong

README.md

@@ -73,7 +73,7 @@ cat file-to-parse | tabularize -
 
 Tabularize operates at the byte level; however, it prints out data as JSON, which does not support bytes. As a result,
 it decodes the data before printing it to the terminal. You can customize the encoding and error resolution strategy
-using the `--encoding` and `errors` options:
+using the `--encoding` and `--errors` options:
 
 ```shell
 tabularize --encoding utf-8 --errors backslashreplace path-to-file

tabularize/__init__.py

@@ -1,3 +1,7 @@
+"""
+Utilities for parsing semi-structured text data
+"""
+
 from .parse import parse_headers, parse_body
 
 

tabularize/__main__.py

@@ -1,3 +1,7 @@
+"""
+Enables the execution of the CLI by package name
+"""
+
 if __name__ == "__main__":
     from . import main
 

tabularize/main.py

@@ -1,3 +1,7 @@
+"""
+Provides a command-line interface to the package
+"""
+
 import argparse
 import json
 import sys
@@ -12,6 +16,16 @@ def _parse_file(
     encoding: str = "utf-8",
     errors: str = "backslashreplace",
 ) -> None:
+    """
+    Parses `file` and prints output to standard output.
+
+    :param file: File to parse.
+    :param force_headers: Iterable of header names to use as a heuristic.
+    :param encoding: Encoding to use for decoding.
+    :param errors: Error resolution strategy for decoding.
+    :return: None.
+    """
+
     header_line: bytes = file.readline()
     while not header_line.strip():
         header_line = file.readline()
@@ -40,6 +54,16 @@ def _process_file(
     encoding: str = "utf-8",
     errors: str = "backslashreplace",
 ) -> None:
+    """
+    Opens the appropriate stream and performs parsing.
+
+    :param file_path: Path to file to parse.
+    :param force_headers: Iterable of header names to use as a heuristic.
+    :param encoding: Encoding to use for decoding.
+    :param errors: Error resolution strategy for decoding.
+    :return: None.
+    """
+
     if file_path == "-":
         if sys.stdin.isatty():
             raise RuntimeError("Terminal is attached - cannot process standard input")
@@ -58,6 +82,12 @@ def _process_file(
 
 
 def main() -> None:
+    """
+    Parses inputs from the command-line and prints output to standard output.
+
+    :return: None.
+    """
+
     parser = argparse.ArgumentParser()
     parser.add_argument(
         "--header",
@@ -84,6 +114,8 @@ def main() -> None:
 
     headers: tuple[bytes, ...] = tuple(header.encode() for header in args.header)
     for file_path in args.files:
+        # noinspection PyBroadException
+        # pylint: disable=broad-exception-caught
         try:
             _process_file(
                 file_path,

tabularize/parse.py

@@ -1,3 +1,7 @@
+"""
+Parsing utilities for semi-structured tabular text input
+"""
+
 from typing import TypeAlias, TYPE_CHECKING, Iterable
 
 if TYPE_CHECKING:
@@ -8,6 +12,14 @@
 def parse_headers(
     data: "BytesType", force: Iterable["BytesType"] | None = None
 ) -> tuple["Header", ...]:
+    """
+    Parses a line of data to derive header names and positions.
+
+    :param data: Data to parse.
+    :param force: Iterable of header names to use as a heuristic.
+    :return: Tuple of headers, consisting of a name, start index, and end index.
+    """
+
     extracted_headers: list["Header"] = []
 
     header_start: int = 0
@@ -43,6 +55,14 @@ def parse_headers(
 def parse_body(
     headers: tuple["Header", ...], line: "BytesType"
 ) -> dict[bytes, "BytesType"]:
+    """
+    Parses a body line based on provided headers.
+
+    :param headers: Headers to map data to.
+    :param line: Data to parse.
+    :return: Dictionary of parsed data.
+    """
+
     entry: dict[bytes, "BytesType"] = {}
 
     start_offset: int | None = 0