docs: improves comment and variable naming

Signed-off-by: Jennifer Power <[email protected]>

trestlebot/transformers/__init__.py

@@ -17,4 +17,8 @@
 Trestlebot transformers.
 
 Custom transformers using trestle libs for trestlebot.
+
+The RulesTransformer class is the base class for all transformers pertaining
+to TrestleRule objects. This allows us to have a common interface for all formats
+that express rules.
 """

trestlebot/transformers/csv_transformer.py

@@ -56,7 +56,12 @@
 
 
 class RulesCSVTransformer(RulesTransformer):
-    """Interface for CSV transformer to Rules model."""
+    """
+    Interface for CSV transformer to Rules model.
+
+    Notes: This will transform individual rows of CSV to and from a
+    Trestle object with row compliance with the Trestle CSV requirements.
+    """
 
     def __init__(self) -> None:
         """Initialize."""
@@ -77,6 +82,22 @@ def transform_to_rule(self, row: Dict[str, str]) -> TrestleRule:
             profile=profile,
         )
 
+    def transform_from_rule(self, rule: TrestleRule) -> Dict[str, str]:
+        """Transforms TrestleRule into a row of CSV."""
+        rule_dict: Dict[str, str] = {
+            RULE_ID: rule.name,
+            RULE_DESCRIPTION: rule.description,
+            NAMESPACE: TRESTLE_GENERIC_NS,
+        }
+        merged_dict = {
+            **rule_dict,
+            **self._add_profile(rule.profile),
+            **self._add_component_info(rule.component),
+        }
+        if rule.parameter is not None:
+            merged_dict.update(self._add_parameter(rule.parameter))
+        return merged_dict
+
     def _extract_rule_info(self, row: Dict[str, str]) -> Dict[str, str]:
         """Extract rule information from a CSV row."""
         return {
@@ -117,22 +138,6 @@ def _extract_component_info(self, row: Dict[str, str]) -> ComponentInfo:
             description=row.get(csv_to_oscal_cd.COMPONENT_DESCRIPTION, ""),
         )
 
-    def transform_from_rule(self, rule: TrestleRule) -> Dict[str, str]:
-        """Rules YAML data into a row of CSV."""
-        rule_dict: Dict[str, str] = {
-            RULE_ID: rule.name,
-            RULE_DESCRIPTION: rule.description,
-            NAMESPACE: TRESTLE_GENERIC_NS,
-        }
-        merged_dict = {
-            **rule_dict,
-            **self._add_profile(rule.profile),
-            **self._add_component_info(rule.component),
-        }
-        if rule.parameter is not None:
-            merged_dict.update(self._add_parameter(rule.parameter))
-        return merged_dict
-
     def _add_profile(self, profile: Profile) -> Dict[str, str]:
         """Add a profile to the CSV Row."""
         controls_list: List[str] = [control.id for control in profile.include_controls]

trestlebot/transformers/yaml_transformer.py

@@ -46,20 +46,21 @@ def __init__(self) -> None:
         super().__init__()
 
     def transform_to_rule(self, blob: str) -> TrestleRule:
-        """Rules YAML data into a row of CSV."""
+        """Transform YAML data into a TrestleRule object."""
         trestle_rule: TrestleRule = self._ingest_yaml(blob)
         return trestle_rule
 
     def transform_from_rule(self, trestle: TrestleRule) -> str:
-        """Rules YAML data into a row of CSV."""
+        """Transform TrestleRule object into YAML data."""
         return self._write_yaml(trestle)
 
     @staticmethod
     def _write_yaml(rule: TrestleRule) -> str:
         """Write the YAML to a string."""
-        yaml = YAML()
-        yaml.default_flow_style = False
-        yaml_data: Dict[str, Any] = {
+        yaml_obj = YAML()
+        yaml_obj.default_flow_style = False
+
+        rule_info: Dict[str, Any] = {
             const.RULE_INFO_TAG: {
                 const.NAME: rule.name,
                 const.DESCRIPTION: rule.description,
@@ -71,12 +72,13 @@ def _write_yaml(rule: TrestleRule) -> str:
         }
 
         if rule.parameter is not None:
-            yaml_data[const.RULE_INFO_TAG][const.PARAMETER] = rule.parameter.dict(
+            rule_info[const.RULE_INFO_TAG][const.PARAMETER] = rule.parameter.dict(
                 by_alias=True, exclude_unset=True
             )
 
         yaml_stream = StringIO()
-        yaml.dump(yaml_data, yaml_stream)
+        yaml_obj.dump(rule_info, yaml_stream)
+
         return yaml_stream.getvalue()
 
     @staticmethod