doc: make code obey python documentation style

Author: SGSSGene

schema_salad/cpp_codegen.py

@@ -58,27 +58,35 @@ def safename2(name: Dict[str, str]) -> str:
     return safename(name["namespace"]) + "::" + safename(name["classname"])
 
 
-# Splits names like https://xyz.xyz/blub#cwl/class
-# into its class path and non class path
 def split_name(s: str) -> Tuple[str, str]:
+    """Split url name into its components.
+
+    Splits names like https://xyz.xyz/blub#cwl/class
+    into its class path and non class path
+    """
     t = s.split("#")
     if len(t) != 2:
         raise ValueError("Expected field to be formatted as 'https://xyz.xyz/blub#cwl/class'.")
     return (t[0], t[1])
 
 
-# similar to split_name but for field names
 def split_field(s: str) -> Tuple[str, str, str]:
+    """Split field into its components.
+
+    similar to split_name but for field names
+    """
     (namespace, field) = split_name(s)
     t = field.split("/")
     if len(t) != 2:
         raise ValueError("Expected field to be formatted as 'https://xyz.xyz/blub#cwl/class'.")
     return (namespace, t[0], t[1])
 
 
-# Prototype of a class
 class ClassDefinition:
+    """Prototype of a class."""
+
     def __init__(self, name: str):
+        """Initialize the class definition with a name."""
         self.fullName = name
         self.extends: List[Dict[str, str]] = []
 
@@ -94,9 +102,11 @@ def __init__(self, name: str):
         self.classname = safename(self.classname)
 
     def writeFwdDeclaration(self, target: IO[str], fullInd: str, ind: str) -> None:
+        """Write forward declaration."""
         target.write(f"{fullInd}namespace {self.namespace} {{ struct {self.classname}; }}\n")
 
     def writeDefinition(self, target: IO[Any], fullInd: str, ind: str) -> None:
+        """Write definition of the class."""
         target.write(f"{fullInd}namespace {self.namespace} {{\n")
         target.write(f"{fullInd}struct {self.classname}")
         extends = list(map(safename2, self.extends))
@@ -119,6 +129,7 @@ def writeDefinition(self, target: IO[Any], fullInd: str, ind: str) -> None:
         target.write(f"{fullInd}}}\n\n")
 
     def writeImplDefinition(self, target: IO[str], fullInd: str, ind: str) -> None:
+        """Write definition with implementation."""
         extends = list(map(safename2, self.extends))
 
         if self.abstract:
@@ -151,9 +162,15 @@ def writeImplDefinition(self, target: IO[str], fullInd: str, ind: str) -> None:
         target.write(f"{fullInd}{ind}return n;\n{fullInd}}}\n")
 
 
-# Prototype of a single field of a class
 class FieldDefinition:
+    """Prototype of a single field from a class definition."""
+
     def __init__(self, name: str, typeStr: str, optional: bool, remap: str):
+        """Initialize field definition.
+
+        Creates a new field with name, its type, optional and which field to use to convert
+        from list to map (or empty if it is not possible)
+        """
         self.name = name
         self.typeStr = typeStr
         self.optional = optional
@@ -166,13 +183,16 @@ def writeDefinition(self, target: IO[Any], fullInd: str, ind: str, namespace: st
         target.write(f"{fullInd}heap_object<{typeStr}> {name};\n")
 
 
-# Prototype of an enum definition
 class EnumDefinition:
+    """Prototype of a enum."""
+
     def __init__(self, name: str, values: List[str]):
+        """Initialize enum definition with a name and possible values."""
         self.name = name
         self.values = values
 
     def writeDefinition(self, target: IO[str], ind: str) -> None:
+        """Write enum definition to output."""
         namespace = ""
         if len(self.name.split("#")) == 2:
             (namespace, classname) = split_name(self.name)
@@ -214,12 +234,14 @@ def writeDefinition(self, target: IO[str], ind: str) -> None:
 
 # !TODO way tot many functions, most of these shouldn't exists
 def isPrimitiveType(v: Any) -> bool:
+    """Check if v is a primitve type."""
     if not isinstance(v, str):
         return False
     return v in ["null", "boolean", "int", "long", "float", "double", "string"]
 
 
 def hasFieldValue(e: Any, f: str, v: Any) -> bool:
+    """Check if e has a field f value."""
     if not isinstance(e, dict):
         return False
     if f not in e:
@@ -228,10 +250,12 @@ def hasFieldValue(e: Any, f: str, v: Any) -> bool:
 
 
 def isRecordSchema(v: Any) -> bool:
+    """Check if v is of type record schema."""
     return hasFieldValue(v, "type", "record")
 
 
 def isEnumSchema(v: Any) -> bool:
+    """Check if v is of type enum schema."""
     if not hasFieldValue(v, "type", "enum"):
         return False
     if "symbols" not in v:
@@ -242,6 +266,7 @@ def isEnumSchema(v: Any) -> bool:
 
 
 def isArray(v: Any) -> bool:
+    """Check if v is of type array."""
     if not isinstance(v, list):
         return False
     for i in v:
@@ -251,6 +276,7 @@ def isArray(v: Any) -> bool:
 
 
 def pred(i: Any) -> bool:
+    """Check if v is any of the simple types."""
     return (
         isPrimitiveType(i)
         or isRecordSchema(i)
@@ -261,6 +287,7 @@ def pred(i: Any) -> bool:
 
 
 def isArraySchema(v: Any) -> bool:
+    """Check if v is of type array schema."""
     if not hasFieldValue(v, "type", "array"):
         return False
     if "items" not in v:
@@ -285,6 +312,7 @@ def __init__(
         package: str,
         copyright: Optional[str],
     ) -> None:
+        """Initialize the C++ code generator."""
         super().__init__()
         self.base_uri = base
         self.target = target
@@ -389,8 +417,8 @@ def convertTypeToCpp(self, type_declaration: Union[List[Any], Dict[str, Any], st
         type_declaration = ", ".join(type_declaration)
         return f"std::variant<{type_declaration}>"
 
-    # start of our generated file
     def epilogue(self, root_loader: Optional[TypeDef]) -> None:
+        """Generate final part of our cpp file."""
         self.target.write(
             """#pragma once
 
@@ -587,6 +615,7 @@ class heap_object {
         )
 
     def parseRecordField(self, field: Dict[str, Any]) -> FieldDefinition:
+        """Parse a record field."""
         (namespace, classname, fieldname) = split_field(field["name"])
         remap = ""
         if "jsonldPredicate" in field:
@@ -606,6 +635,7 @@ def parseRecordField(self, field: Dict[str, Any]) -> FieldDefinition:
         return FieldDefinition(name=fieldname, typeStr=fieldtype, optional=False, remap=remap)
 
     def parseRecordSchema(self, stype: Dict[str, Any]) -> None:
+        """Parse a record schema."""
         cd = ClassDefinition(name=stype["name"])
         cd.abstract = stype.get("abstract", False)
 
@@ -626,6 +656,7 @@ def parseRecordSchema(self, stype: Dict[str, Any]) -> None:
         self.classDefinitions[stype["name"]] = cd
 
     def parseEnum(self, stype: Dict[str, Any]) -> str:
+        """Parse a schema salad enum."""
         name = cast(str, stype["name"])
         if name not in self.enumDefinitions:
             self.enumDefinitions[name] = EnumDefinition(
@@ -634,6 +665,11 @@ def parseEnum(self, stype: Dict[str, Any]) -> str:
         return name
 
     def parse(self, items: List[Dict[str, Any]]) -> None:
+        """Parse sechema salad items.
+
+        This function is being called from the outside and drives
+        the whole code generation.
+        """
         for stype in items:
             if "type" in stype and stype["type"] == "documentation":
                 continue