[Penify]: Documentation for commit - 61bb1ce

docstring_parser/cli.py

@@ -14,7 +14,14 @@
 
 
 def main():
-    """Entry point for the command-line interface."""
+    """Entry point for the command-line interface.
+
+    This function sets up an argument parser to handle different commands (`parse`,
+    `compose`, and `remove`) related to JSDoc strings. It processes the input data
+    based on the specified command, performs the required operations (parsing,
+    composing, or removing components), and handles errors appropriately. The
+    results are then output to either a file or standard output.
+    """
     parser = argparse.ArgumentParser(description='Parse and compose JSDoc strings')
     subparsers = parser.add_subparsers(dest='command', required=True, help='Command to execute')
 

docstring_parser/composer.py

@@ -4,18 +4,19 @@
 
 
 def compose_jsdoc(jsdoc_obj: Dict[str, Any]) -> str:
-    """
-    Compose a JSDoc string from a structured dictionary.
+    """Compose a JSDoc string from a structured dictionary.
+
+    This function constructs a JSDoc comment based on the provided dictionary
+    structure, handling various components such as descriptions, parameters,
+    returns, throws, examples, and other tags. It ensures that each section is
+    correctly formatted and included in the final JSDoc string if present in the
+    input dictionary.
 
     Args:
-        jsdoc_obj (Dict[str, Any]): The dictionary representing the JSDoc structure
-        
+        jsdoc_obj (Dict[str, Any]): The dictionary representing the JSDoc structure.
+
     Returns:
-        str: The formatted JSDoc string
-
-    Example:
-        >>> compose_jsdoc({'description': 'Description', 'params': [{'name': 'name', 'type': 'string', 'description': 'The name'}]})
-        '/**\\n * Description\\n * @param {string} name - The name\\n */'
+        str: The formatted JSDoc string.
     """
     lines = ['/**']
 

docstring_parser/parser.py

@@ -5,20 +5,21 @@
 
 
 def parse_jsdoc(docstring: str) -> Dict[str, Any]:
-    """
-    Parse a JSDoc string into a structured dictionary.
+    # Initialize the result dictionary
+    """Parse a JSDoc string into a structured dictionary.
+
+    This function processes a JSDoc string to extract structured information such
+    as description, parameters, return values, exceptions, examples, and other
+    tags. It handles the removal of opening and closing markers, splits the content
+    into lines, and categorizes each line based on whether it is part of a tag or
+    the main description.
 
     Args:
-        docstring (str): The JSDoc string to parse
-
-    Returns:
-        Dict[str, Any]: A dictionary representing the parsed JSDoc structure
+        docstring (str): The JSDoc string to parse.
 
-    Example:
-        >>> parse_jsdoc("/**\\n * Description\\n * @param {string} name - The name\\n */")
-        {'description': 'Description', 'params': [{'name': 'name', 'type': 'string', 'description': 'The name'}]}
+    Returns:
+        Dict[str, Any]: A dictionary representing the parsed JSDoc structure.
     """
-    # Initialize the result dictionary
     result = {
         'description': '',
         'params': [],
@@ -88,13 +89,20 @@ def parse_jsdoc(docstring: str) -> Dict[str, Any]:
 
 
 def _process_tag(tag: str, content: List[str], result: Dict[str, Any]) -> None:
-    """
-    Process a JSDoc tag and update the result dictionary.
+    """Process a JSDoc tag and update the result dictionary.
+
+    The function processes different types of JSDoc tags such as `param`,
+    `returns`, `throws`, `example`, and others, updating the provided result
+    dictionary accordingly.
 
     Args:
-        tag (str): The tag name (without the @ symbol)
-        content (List[str]): The content lines associated with the tag
-        result (Dict[str, Any]): The dictionary to update
+        tag (str): The tag name (without the @ symbol).
+        content (List[str]): The content lines associated with the tag.
+        result (Dict[str, Any]): The dictionary to update.
+
+    Returns:
+        None: The function modifies the `result` dictionary in place and does not return any
+            value.
     """
     content_str = ' '.join(content).strip()
 

docstring_parser/utils.py

@@ -5,22 +5,20 @@
 
 
 def extract_type_info(type_str: str) -> Dict[str, Any]:
-    """
-    Extract detailed type information from a JSDoc type string.
+    """Extract detailed type information from a JSDoc type string.
+
+    This function parses the input type string to determine if it represents a
+    union of types, a generic/template type with parameters, or a simple type. It
+    returns a dictionary containing the parsed type information.
 
     Args:
-        type_str (str): The type string from a JSDoc tag
-        
+        type_str (str): The type string from a JSDoc tag.
+
     Returns:
-        Dict[str, Any]: A dictionary with parsed type information
-
-    Example:
-        >>> extract_type_info('Array<string>')
-        {'name': 'Array', 'params': ['string']}
-        >>> extract_type_info('Object<string, number>')
-        {'name': 'Object', 'params': ['string', 'number']}
-        >>> extract_type_info('string|number')
-        {'union': ['string', 'number']}
+        Dict[str, Any]: A dictionary with parsed type information.
+            - If the type is a union, it includes a 'union' key with a list of types.
+            - If the type is generic/template, it includes 'name' and 'params' keys.
+            - If the type is simple, it only includes a 'name' key.
     """
     result = {}
 
@@ -65,15 +63,19 @@ def extract_type_info(type_str: str) -> Dict[str, Any]:
 
 
 def merge_jsdoc_objects(base: Dict[str, Any], overlay: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Merge two JSDoc objects, with the overlay taking precedence.
+    """Merge two JSDoc objects, with the overlay taking precedence.
+
+    The function merges two dictionaries representing JSDoc objects. If a key
+    exists in both the base and overlay, the value from the overlay takes
+    precedence. For keys like 'params' and 'throws', it combines the lists while
+    ensuring that items with matching names are updated rather than duplicated.
 
     Args:
-        base (Dict[str, Any]): The base JSDoc object
-        overlay (Dict[str, Any]): The overlay JSDoc object that takes precedence
-        
+        base (Dict[str, Any]): The base JSDoc object.
+        overlay (Dict[str, Any]): The overlay JSDoc object that takes precedence.
+
     Returns:
-        Dict[str, Any]: The merged JSDoc object
+        Dict[str, Any]: The merged JSDoc object.
     """
     result = base.copy()
 
@@ -128,16 +130,21 @@ def merge_jsdoc_objects(base: Dict[str, Any], overlay: Dict[str, Any]) -> Dict[s
 
 
 def remove_jsdoc_component(jsdoc_obj: Dict[str, Any], component_type: str, identifier: Optional[str] = None) -> Dict[str, Any]:
-    """
-    Remove a component from a JSDoc object.
+    """Remove a specified component from a JSDoc object.
+
+    This function modifies the provided JSDoc object by removing a component based
+    on the given type and identifier.  If no identifier is provided, it removes all
+    instances of the component type. The function handles various  component types
+    such as 'description', 'param', 'returns', 'throws', 'example', and 'tag'.
 
     Args:
-        jsdoc_obj (Dict[str, Any]): The JSDoc object
-        component_type (str): The component type to remove ('param', 'returns', 'throws', 'example', 'tag')
-        identifier (Optional[str]): The identifier of the component (e.g., param name, tag name)
-
+        jsdoc_obj (Dict[str, Any]): The JSDoc object to be modified.
+        component_type (str): The type of component to remove ('param', 'returns', 'throws', 'example',
+            'tag').
+        identifier (Optional[str]): An optional identifier to specify which instance of the component to remove.
+
     Returns:
-        Dict[str, Any]: The modified JSDoc object
+        Dict[str, Any]: The modified JSDoc object with the specified component removed.
     """
     result = jsdoc_obj.copy()