add descriptions to each option of SerializerOptions, DeserializerOptions and FormatterOptions

Author: kkozik-amplify

cli/hcl_to_json.py

@@ -68,7 +68,7 @@ def main():
     parser.add_argument(
         "--no-explicit-blocks",
         action="store_true",
-        help="Disable explicit block markers",
+        help="Disable explicit block markers. Note: round-trip through json_to_hcl is NOT supported with this option.",
     )
     parser.add_argument(
         "--no-preserve-heredocs",
@@ -88,7 +88,7 @@ def main():
     parser.add_argument(
         "--strip-string-quotes",
         action="store_true",
-        help="Strip surrounding double-quotes from serialized string values",
+        help="Strip surrounding double-quotes from serialized string values. Note: round-trip through json_to_hcl is NOT supported with this option.",
     )
 
     # JSON output formatting

hcl2/deserializer.py

@@ -63,9 +63,15 @@
 class DeserializerOptions:
     """Options controlling how Python dicts are deserialized into LarkElement trees."""
 
+    # Convert heredoc values (<<EOF...EOF) to regular escaped strings during
+    # deserialization. When False, heredoc syntax is preserved as-is.
     heredocs_to_strings: bool = False
+    # Convert multi-line escaped strings (containing \n) back into heredoc
+    # syntax (<<EOF...EOF) during deserialization.
     strings_to_heredocs: bool = False
+    # Use colon (:) instead of equals (=) as the separator in object elements.
     object_elements_colon: bool = False
+    # Append a trailing comma after each object element.
     object_elements_trailing_comma: bool = True
     # with_comments: bool = False # TODO
 

hcl2/formatter.py

@@ -32,12 +32,20 @@
 class FormatterOptions:
     """Options controlling whitespace formatting of LarkElement trees."""
 
+    # Number of spaces per indentation level.
     indent_length: int = 2
+    # Use multi-line format for empty blocks (opening brace on same line,
+    # closing brace on next). When False, empty blocks collapse to "{}".
     open_empty_blocks: bool = True
+    # Use multi-line format for empty objects. When False, empty objects
+    # collapse to "{}".
     open_empty_objects: bool = False
+    # Use multi-line format for empty tuples. When False, empty tuples
+    # collapse to "[]".
     open_empty_tuples: bool = False
-
+    # Pad attribute equals signs so they align vertically within a block body.
     vertically_align_attributes: bool = True
+    # Pad object element equals/colons so they align vertically within an object.
     vertically_align_object_elements: bool = True
 
 

hcl2/utils.py

@@ -11,13 +11,26 @@
 class SerializationOptions:
     """Options controlling how LarkElement trees are serialized to Python dicts."""
 
+    # Include __comments__ and __inline_comments__ keys in the output.
     with_comments: bool = True
+    # Add __start_line__ and __end_line__ metadata to each block/attribute.
     with_meta: bool = False
+    # Serialize nested objects as inline HCL strings (e.g. "${{key = value}}")
+    # instead of Python dicts.
     wrap_objects: bool = False
+    # Serialize tuples as inline HCL strings (e.g. "${[1, 2, 3]}")
+    # instead of Python lists.
     wrap_tuples: bool = False
+    # Add __is_block__ markers to distinguish blocks from plain objects.
+    # Note: round-trip through from_dict/dumps is NOT supported WITHOUT this option.
     explicit_blocks: bool = True
+    # Keep heredoc syntax (<<EOF...EOF) in output. When False, heredocs are
+    # converted to regular escaped strings.
     preserve_heredocs: bool = True
+    # Wrap all binary/unary operations in parentheses for explicit precedence.
     force_operation_parentheses: bool = False
+    # Keep scientific notation for floats (e.g. 1e10). When False, expand to
+    # standard decimal form.
     preserve_scientific_notation: bool = True
     # Remove surrounding double-quotes from serialized string values,
     # producing backwards-compatible output (e.g. "hello" instead of '"hello"').