Add some more docstrings

Author: mr-c

schema_salad/avro/schema.py

@@ -385,6 +385,7 @@ def __init__(
     # read-only properties
     @property
     def symbols(self) -> list[str]:
+        """Retrieve the list of symbols."""
         return cast(list[str], self.get_prop("symbols"))
 
 
@@ -596,6 +597,7 @@ def __init__(
     # read-only properties
     @property
     def schemas(self) -> list[Schema]:
+        """Retrieve the list of schemas."""
         return self._schemas
 
 
@@ -664,6 +666,7 @@ def __init__(
     # read-only properties
     @property
     def fields(self) -> list[Field]:
+        """Retrieve the fields list."""
         return cast(list[Field], self.get_prop("fields"))
 
 

schema_salad/dotnet_codegen.py

@@ -502,6 +502,7 @@ def type_loader(
         return self.collected_types[self.safe_name(type_declaration) + "Loader"]
 
     def type_loader_enum(self, type_declaration: dict[str, Any]) -> TypeDef:
+        """Build an enum type loader for the given declaration."""
         for sym in type_declaration["symbols"]:
             self.add_vocab(shortname(sym), sym)
         enum_name = self.safe_name(type_declaration["name"])

schema_salad/exceptions.py

@@ -75,6 +75,7 @@ def with_sourceline(self, sl: Optional[SourceLine]) -> "SchemaSaladException":
         return self
 
     def leaves(self) -> list["SchemaSaladException"]:
+        """Return the list of all the exceptions at the tips of the tree."""
         if len(self.children) > 0:
             return sum((c.leaves() for c in self.children), [])
         if len(self.message):

schema_salad/fetcher.py

@@ -65,6 +65,7 @@ def __init__(
         self.session = session
 
     def fetch_text(self, url: str, content_types: Optional[list[str]] = None) -> str:
+        """Retrieve the given resource as a string."""
         result = self.cache.get(url, None)
         if isinstance(result, str):
             return result

schema_salad/java_codegen.py

@@ -580,6 +580,7 @@ def type_loader(
         return self.collected_types[self.safe_name(type_declaration)]
 
     def type_loader_enum(self, type_declaration: dict[str, Any]) -> TypeDef:
+        """Build an enum type loader for the given declaration."""
         symbols = [self.property_name(sym) for sym in type_declaration["symbols"]]
         for sym in symbols:
             self.add_vocab(shortname(sym), sym)

schema_salad/main.py

@@ -227,6 +227,7 @@ def arg_parser() -> argparse.ArgumentParser:
 
 
 def main(argsl: Optional[list[str]] = None) -> int:
+    """Run the schema-salad-tool."""
     if argsl is None:
         argsl = sys.argv[1:]
 

schema_salad/makedoc.py

@@ -43,6 +43,7 @@ def vocab_type_name(url: str) -> str:
 
 
 def has_types(items: Any) -> list[str]:
+    """Retrieve all the types of a record."""
     r: list[str] = []
     if isinstance(items, MutableMapping):
         if items["type"] == "https://w3id.org/cwl/salad#record":
@@ -225,6 +226,7 @@ def number_headings(toc: ToC, maindoc: str) -> str:
 
 
 def fix_doc(doc: Union[list[str], str]) -> str:
+    """Concatenate doc strings, replacing email addresses with mailto links."""
     docstr = "".join(doc) if isinstance(doc, MutableSequence) else doc
     return "\n".join(
         [re.sub(r"<([^>@]+@[^>]+)>", r"[\1](mailto:\1)", d) for d in docstr.splitlines()]
@@ -381,6 +383,7 @@ def typefmt(
         raise SchemaSaladException("We should not be here!")
 
     def render_type(self, f: dict[str, Any], depth: int) -> None:
+        """Render a type declaration."""
         if f["name"] in self.rendered or f["name"] in self.redirects:
             return
         self.rendered.add(f["name"])

schema_salad/ref_resolver.py

@@ -277,9 +277,11 @@ def _add_properties(self, s: str) -> None:
         self.foreign_properties.add(str(s))
 
     def add_namespaces(self, ns: dict[str, str]) -> None:
+        """Add the given namespace to our vocab list."""
         self.vocab.update(ns)
 
     def add_schemas(self, ns: Union[list[str], str], base_url: str) -> None:
+        """Fetch exernal schemas and add them to the graph."""
         if self.skip_schemas:
             return
         for sch in aslist(ns):

schema_salad/schema.py

@@ -750,6 +750,7 @@ def make_avro_schema(
 
 
 def make_avro_schema_from_avro(avro: list[Union[Avro, dict[str, str], str]]) -> Names:
+    """Create avro.schema.Names from the given definitions."""
     names = Names()
     make_avsc_object(convert_to_dict(avro), names)
     return names

schema_salad/sourceline.py

@@ -88,6 +88,7 @@ def lineno(i: int, line: str) -> str:
 
 
 def bullets(textlist: list[str], bul: str) -> str:
+    """Indent using the specified number of bullets."""
     if len(textlist) == 1:
         return textlist[0]
     return "\n".join(indent(t, bullet=bul) for t in textlist)
@@ -245,6 +246,7 @@ def file(self) -> Optional[str]:
         return None
 
     def start(self) -> Optional[tuple[int, int]]:
+        """Determine the starting location."""
         if self.file() is None:
             return None
         if self.key is None or self.item.lc.data is None or self.key not in self.item.lc.data:
@@ -255,6 +257,7 @@ def start(self) -> Optional[tuple[int, int]]:
         )
 
     def end(self) -> Optional[tuple[int, int]]:
+        """Empty, for now."""
         return None
 
     def makeLead(self) -> str: