uniformed docstrings for docs (#4)

mapry/cpp/generate/jsoncpp_header.py

@@ -1,4 +1,4 @@
-"""Generate the header that defines translation from/to Jsoncpp values."""
+"""Generate the header for de/serialization from/to Jsoncpp values."""
 
 from typing import List, Sequence, Set, Union  # pylint: disable=unused-import
 
@@ -198,15 +198,15 @@ def generate(
         graph: mapry.Graph, cpp: mapry.Cpp, types_header_path: str,
         parse_header_path: str) -> str:
     """
-    Generate the content of the header file.
+    Generate the header file for de/serialization from/to Jsoncpp.
 
     :param graph: definition of the object graph
     :param cpp: C++ settings
     :param types_header_path:
         path to the header file that defines the types of the object graph
     :param parse_header_path:
         path to the header file that defines the general parsing structures
-    :return: generated code
+    :return: content of the header file
     """
     blocks = [
         "#pragma once", mapry.cpp.generate.WARNING,

mapry/cpp/generate/jsoncpp_impl.py

@@ -1,4 +1,4 @@
-"""Generate the code to translate object graphs from/to Jsoncpp values."""
+"""Generate the implementation of de/serialization from/to Jsoncpp values."""
 
 # pylint: disable=too-many-lines
 # pylint: disable=too-many-arguments
@@ -475,7 +475,7 @@ def _value_type_to_string() -> str:
         }''')
 
 
-class AutoID:
+class _AutoID:
     """Keep track of parsing identifiers."""
 
     def __init__(self) -> None:
@@ -526,7 +526,7 @@ def next_identifier(self) -> str:
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_boolean(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        auto_id: AutoID) -> str:
+        auto_id: _AutoID) -> str:
     """
     Generate the code to parse a boolean.
 
@@ -623,7 +623,7 @@ def _parse_boolean(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_integer(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Integer, auto_id: AutoID) -> str:
+        a_type: mapry.Integer, auto_id: _AutoID) -> str:
     """
     Generate the code to parse an integer.
 
@@ -721,7 +721,7 @@ def _parse_integer(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_float(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Float, auto_id: AutoID) -> str:
+        a_type: mapry.Float, auto_id: _AutoID) -> str:
     """
     Generate the code to parse a floating-point number.
 
@@ -800,7 +800,7 @@ def _parse_float(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_string(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.String, auto_id: AutoID) -> str:
+        a_type: mapry.String, auto_id: _AutoID) -> str:
     """
     Generate the code to parse a string.
 
@@ -892,7 +892,7 @@ def _parse_string(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_path(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Path, auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        a_type: mapry.Path, auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a path.
 
@@ -1013,7 +1013,7 @@ def _parse_path(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_date(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Date, auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        a_type: mapry.Date, auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a date.
 
@@ -1052,7 +1052,7 @@ def _parse_date(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_date_time(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Datetime, auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        a_type: mapry.Datetime, auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a date-time.
 
@@ -1141,7 +1141,7 @@ def _parse_date_time(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_time(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Time, auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        a_type: mapry.Time, auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a time.
 
@@ -1248,7 +1248,7 @@ def _parse_time(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_time_zone(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.TimeZone, auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        a_type: mapry.TimeZone, auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a time zone.
 
@@ -1331,7 +1331,7 @@ def _parse_time_zone(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_duration(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Duration, auto_id: AutoID) -> str:
+        a_type: mapry.Duration, auto_id: _AutoID) -> str:
     """
     Generate the code to parse a duration.
 
@@ -1426,7 +1426,7 @@ def _parse_duration(
 def _parse_array(
         value_expr: str, target_expr: str, ref_parts: List[str],
         a_type: mapry.Array, registry_exprs: Mapping[mapry.Class, str],
-        auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse an array.
 
@@ -1505,7 +1505,7 @@ def _parse_array(
 def _parse_map(
         value_expr: str, target_expr: str, ref_parts: List[str],
         a_type: mapry.Map, registry_exprs: Mapping[mapry.Class, str],
-        auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a map.
 
@@ -1586,7 +1586,7 @@ def _parse_map(
 @ensure(lambda result: not result.endswith('\n'))
 def _parse_instance_reference(
         value_expr: str, target_expr: str, ref_parts: List[str],
-        a_type: mapry.Class, registry_expr: str, auto_id: AutoID) -> str:
+        a_type: mapry.Class, registry_expr: str, auto_id: _AutoID) -> str:
     """
     Generate the code to parse a reference to an instance of a class.
 
@@ -1637,7 +1637,7 @@ def _parse_instance_reference(
 def _parse_embed(
         value_expr: str, target_expr: str, ref_parts: List[str],
         a_type: mapry.Embed, registry_exprs: Mapping[mapry.Class, str],
-        auto_id: AutoID) -> str:
+        auto_id: _AutoID) -> str:
     """
     Generate the code to parse an embeddable structure.
 
@@ -1673,7 +1673,7 @@ def _parse_embed(
 def _parse_value(
         value_expr: str, target_expr: str, ref_parts: List[str],
         a_type: mapry.Type, registry_exprs: Mapping[mapry.Class, str],
-        auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse the the ``value_expr`` into the ``target_expr``.
 
@@ -1852,7 +1852,7 @@ def _parse_value(
 def _parse_property(
         target_obj_expr: str, value_obj_expr: str, ref_obj_parts: List[str],
         a_property: mapry.Property, registry_exprs: Mapping[mapry.Class, str],
-        auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to parse a property of a composite from a JSON object.
 
@@ -1964,7 +1964,7 @@ def _parse_composite(
     }
     # yapf: enable
 
-    auto_id = AutoID()
+    auto_id = _AutoID()
 
     # yapf: disable
     property_parsing = {
@@ -2169,7 +2169,7 @@ def _parse_graph(graph: mapry.Graph, cpp: mapry.Cpp) -> str:
     # in the template
     property_parsings = []  # type: List[str]
 
-    auto_id = AutoID()
+    auto_id = _AutoID()
     for prop in graph.properties.values():
         property_parsings.append(
             _parse_property(
@@ -2450,8 +2450,8 @@ def _serialize_time_zone(
 
 @ensure(lambda result: not result.endswith('\n'))
 def _serialize_array(
-        target_expr: str, value_expr: str, a_type: mapry.Array, auto_id: AutoID,
-        cpp: mapry.Cpp) -> str:
+        target_expr: str, value_expr: str, a_type: mapry.Array,
+        auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to serialize an array.
 
@@ -2493,7 +2493,7 @@ def _serialize_array(
 
 @ensure(lambda result: not result.endswith('\n'))
 def _serialize_map(
-        target_expr: str, value_expr: str, a_type: mapry.Map, auto_id: AutoID,
+        target_expr: str, value_expr: str, a_type: mapry.Map, auto_id: _AutoID,
         cpp: mapry.Cpp) -> str:
     """
     Generate the code to serialize a map.
@@ -2525,7 +2525,7 @@ def _serialize_map(
 
 @ensure(lambda result: not result.endswith('\n'))
 def _serialize_value(
-        target_expr: str, value_expr: str, a_type: mapry.Type, auto_id: AutoID,
+        target_expr: str, value_expr: str, a_type: mapry.Type, auto_id: _AutoID,
         cpp: mapry.Cpp) -> str:
     """
     Generate the code to serialize the ``value_expr`` into the ``target_expr``.
@@ -2608,7 +2608,7 @@ def _serialize_value(
 @ensure(lambda result: not result.endswith('\n'))
 def _serialize_property(
         target_expr: str, value_expr: str, a_property: mapry.Property,
-        auto_id: AutoID, cpp: mapry.Cpp) -> str:
+        auto_id: _AutoID, cpp: mapry.Cpp) -> str:
     """
     Generate the code to serialize the property.
 
@@ -2679,7 +2679,7 @@ def _serialize_class_or_embed(
     """
     value_expr = mapry.cpp.naming.as_variable(class_or_embed.name)
 
-    auto_id = AutoID()
+    auto_id = _AutoID()
 
     # yapf: disable
     property_serializations = [
@@ -2765,7 +2765,7 @@ def _serialize_graph(graph: mapry.Graph, cpp: mapry.Cpp) -> str:
     """
     value_expr = mapry.cpp.naming.as_variable(graph.name)
 
-    auto_id = AutoID()
+    auto_id = _AutoID()
 
     # yapf: disable
     property_serializations = [
@@ -2790,15 +2790,15 @@ def generate(
         graph: mapry.Graph, cpp: mapry.Cpp, types_header_path: str,
         parse_header_path: str, jsoncpp_header_path: str) -> str:
     """
-    Generate the de/serialization from/to Jsoncpp values.
+    Generate the implementation file for de/serialization from/to Jsoncpp.
 
     :param graph: definition of the object graph
     :param cpp: C++ settings
     :param types_header_path: defines the types of the object graph
     :param parse_header_path: defines the general parsing structures
     :param jsoncpp_header_path:
         defines parsing and serializing functions from/to Jsoncpp
-    :return: generated code
+    :return: content of the implementation file
     """
     ##
     # Header

mapry/cpp/generate/parse_header.py

@@ -75,10 +75,10 @@ class Errors {
 @ensure(lambda result: result.endswith('\n'))
 def generate(cpp: mapry.Cpp) -> str:
     """
-    Generate the header file defining the types of the object graph.
+    Generate the header file defining the parsing structures.
 
     :param cpp: C++ settings
-    :return: generated code
+    :return: content of the header file
     """
     blocks = [
         "#pragma once", mapry.cpp.generate.WARNING,

mapry/cpp/generate/parse_impl.py

@@ -46,12 +46,12 @@ def _parse_errors() -> str:
 @ensure(lambda result: result.endswith('\n'))
 def generate(cpp: mapry.Cpp, parse_header_path: str) -> str:
     """
-    Generate the implementation of the types of the object graph.
+    Generate the implementation file of the parsing structures.
 
     :param cpp: C++ settings
     :param parse_header_path:
         path to the header file that defines the general parsing structures
-    :return: generated code
+    :return: content of the implementation file
     """
     blocks = [
         mapry.cpp.generate.WARNING, '#include "{}"'.format(parse_header_path),

mapry/cpp/generate/types_header.py

@@ -367,11 +367,11 @@ def _graph_definition(graph: mapry.Graph, cpp: mapry.Cpp) -> str:
 @ensure(lambda result: result.endswith('\n'))
 def generate(graph: mapry.Graph, cpp: mapry.Cpp) -> str:
     """
-    Generate the the header file that defines the types of the object graph.
+    Generate the header file that defines the types of the object graph.
 
     :param graph: definition of the object graph
     :param cpp: C++ settings
-    :return: generated code
+    :return: content of the header file
     """
     blocks = [
         "#pragma once", mapry.cpp.generate.WARNING,

mapry/go/generate/fromjsonable.py

@@ -1781,11 +1781,11 @@ def _parse_graph(
 @ensure(lambda result: result.endswith('\n'))
 def generate(graph: mapry.Graph, go: mapry.Go) -> str:
     """
-    Generate the code to parse an object graph from a JSONable object.
+    Generate the source file to parse an object graph from a JSONable object.
 
     :param graph: mapry definition of the object graph
     :param go: Go settings
-    :return: generated code
+    :return: content of the source file
     """
     blocks = [
         'package {}'.format(go.package),

mapry/go/generate/fromjsonable_test.py

@@ -136,11 +136,11 @@ def _example_duration_from_string() -> str:
 @ensure(lambda result: result.endswith('\n'))
 def generate(graph: mapry.Graph, go: mapry.Go) -> str:
     """
-    Generate the code to test parsing an object graph from a JSONable object.
+    Generate the source file to test parsing from a JSONable object.
 
     :param graph: mapry definition of the object graph
     :param go: Go settings
-    :return: generated code
+    :return: content of the source file
     """
     blocks = [
         'package {}'.format(go.package),

mapry/go/generate/parse.py

@@ -69,9 +69,9 @@
 @ensure(lambda result: result.endswith('\n'))
 def generate(go: mapry.Go) -> str:
     """
-    Generate the code to define general structures required for parsing.
+    Generate the souce file to define general structures required for parsing.
 
-    :return: generated code
+    :return: content of the source file
     """
     blocks = [
         "package {}".format(go.package), mapry.go.generate.WARNING,

mapry/go/generate/tojsonable.py

@@ -543,11 +543,11 @@ def _serialize_graph(graph: mapry.Graph, go: mapry.Go) -> str:
 @ensure(lambda result: result.endswith('\n'))
 def generate(graph: mapry.Graph, go: mapry.Go) -> str:
     """
-    Generate the code to parse an object graph from a JSONable object.
+    Generate the source file to serialize an object graph to a JSONable object.
 
     :param graph: mapry definition of the object graph
     :param go: Go settings
-    :return: generated code
+    :return: content of the source file
     """
     blocks = [
         'package {}'.format(go.package),

mapry/go/generate/tojsonable_test.py

@@ -90,11 +90,11 @@ def _example_duration_to_string() -> str:
 @ensure(lambda result: result.endswith('\n'))
 def generate(graph: mapry.Graph, go: mapry.Go) -> str:
     """
-    Generate the code to test serializing an object graph from a JSONable.
+    Generate the source file to test serializing to a JSONable.
 
     :param graph: mapry definition of the object graph
     :param go: Go settings
-    :return: generated code
+    :return: content of the source file
     """
     blocks = [
         'package {}'.format(go.package),

mapry/go/generate/types.py

@@ -178,11 +178,11 @@ def _define_graph(graph: mapry.Graph, go: mapry.Go) -> str:
 @ensure(lambda result: result.endswith('\n'))
 def generate(graph: mapry.Graph, go: mapry.Go) -> str:
     """
-    Generate the code that defines the types of the object graph.
+    Generate the source file that defines the types of the object graph.
 
     :param graph: definition of the object graph
     :param go: Go settings
-    :return: generated code
+    :return: content of the source file
     """
     blocks = ['package {}'.format(go.package), mapry.go.generate.WARNING]