def-file docs

src/kyupy/def_file.py

@@ -1,3 +1,9 @@
+"""A simple and incomplete parser for the Design Exchange Format (DEF).
+
+This parser extracts information on components and nets from DEF files and make them available
+as an intermediate representation (:class:`DefFile` object).
+"""
+
 from collections import defaultdict
 
 from lark import Lark, Transformer, Tree
@@ -69,6 +75,7 @@ class DefPin:
 
 
 class DefFile:
+    """Intermediate representation of a DEF file."""
     def __init__(self):
         self.rows = []
         self.tracks = []
@@ -278,8 +285,13 @@ GRAMMAR = r"""
 
 
 def parse(text):
+    """Parses the given ``text`` and returns a :class:`DefFile` object."""
     return Lark(GRAMMAR, parser="lalr", transformer=DefTransformer()).parse(text)
 
 
 def load(file):
+    """Parses the contents of ``file`` and returns a :class:`DefFile` object.
+
+    Files with `.gz`-suffix are decompressed on-the-fly.
+    """
     return parse(readtext(file))