diff --git a/docstring_parser/cli.py b/docstring_parser/cli.py index e59ae01..2e68398 100755 --- a/docstring_parser/cli.py +++ b/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') diff --git a/docstring_parser/composer.py b/docstring_parser/composer.py index d1fc7ae..1b6abf0 100644 --- a/docstring_parser/composer.py +++ b/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 = ['/**'] diff --git a/docstring_parser/parser.py b/docstring_parser/parser.py index d9441de..c5be8f6 100644 --- a/docstring_parser/parser.py +++ b/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() diff --git a/docstring_parser/utils.py b/docstring_parser/utils.py index 64ed630..ff4f33c 100644 --- a/docstring_parser/utils.py +++ b/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') - {'name': 'Array', 'params': ['string']} - >>> extract_type_info('Object') - {'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()