| Name | jsdoc JSON |
| Version |
1.0.3
JSON |
| download |
| home_page | None |
| Summary | A Python package for parsing JSDoc comment blocks into structured BaseModel objects |
| upload_time | 2025-07-27 02:22:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
jsdoc
documentation
parser
javascript
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# JSDoc Parser
A professional Python package for parsing JavaScript documentation comments (JSDoc) into structured Pydantic BaseModel objects.
## Features
- **Comprehensive JSDoc Support**: Parses all major JSDoc tags including `@param`, `@returns`, `@typedef`, `@property`, `@example`, and `@throws`
- **Multiple TypeDef Support**: Parse multiple `@typedef` definitions from single or separate comment blocks
- **Type-Safe**: Built with Pydantic BaseModel for robust data validation and type safety
- **Union Types**: Full support for union types like `string|number|null`
- **Optional Parameters**: Handles optional parameters with bracket syntax `[param]`
- **Code Extraction**: Optionally extracts JavaScript code that follows JSDoc comments
- **Function Name Parsing**: Automatically extracts function names from various JavaScript function definitions
- **Professional API**: Simple `parse()` function interface with detailed structured output
## Installation
```bash
pip install jsdoc
```
## Quick Start
```python
from jsdoc import parse
# Parse a JSDoc comment
jsdoc_string = '''/**
* Adds two numbers together.
* @param {number} a - The first number
* @param {number} b - The second number
* @returns {number} The sum of a and b
* @example
* add(1, 2); // returns 3
*/
function add(a, b) {
return a + b;
}'''
result = parse(jsdoc_string)
# Access structured data
print(result.description.summary) # "Adds two numbers together."
print(result.params[0].name) # "a"
print(result.params[0].types) # ["number"]
print(result.returns[0].types) # ["number"]
print(result.examples[0].code) # "add(1, 2); // returns 3"
print(result.code) # "function add(a, b) {\\n return a + b;\\n}"
print(result.function_name) # "add"
```
## Supported JSDoc Tags
| Tag | Description | Example |
|-----|-------------|---------|
| `@param` | Function parameter | `@param {string} name - User's name` |
| `@returns/@return` | Return value | `@returns {number} Sum of a and b` |
| `@typedef` | Custom type definition | `@typedef {Object} User` |
| `@property` | Object property | `@property {number} age - User's age` |
| `@example` | Usage example | `@example doSomething(123);` |
| `@throws` | Possible exceptions | `@throws {Error} If input is invalid` |
## Output Structure
The `parse()` function returns a `JSDocComment` object with the following structure:
```python
{
"description": {
"full": "Complete description text...",
"summary": "Brief summary sentence."
},
"params": [
{
"types": ["string"],
"name": "param_name",
"description": "Parameter description",
"optional": False
}
],
"returns": [
{
"types": ["number"],
"description": "Return value description"
}
],
"examples": [
{
"code": "example_code();",
"description": None
}
],
"throws": [
{
"types": ["Error"],
"description": "Exception description"
}
],
"typedefs": [
{
"types": ["Object"],
"name": "CustomType",
"description": "Type description",
"properties": [...]
}
],
"properties": [...],
"code": "function code() { ... }",
"function_name": "functionName",
"raw_comment": "/** original comment */"
}
```
## Advanced Usage
### Parsing Without Code Extraction
```python
result = parse(jsdoc_string, include_code=False)
# result.code will be None
```
### Handling TypeDefs with Properties
```python
jsdoc = '''/**
* @typedef {object} User
* @property {string} name - User's name
* @property {number} age - User's age
* @property {string|null} email - User's email (optional)
*/'''
result = parse(jsdoc, include_code=False)
print(result.typedefs[0].name) # "User"
print(result.typedefs[0].properties[0].name) # "name"
print(result.typedefs[0].properties[0].types) # ["string"]
print(result.typedefs[0].properties[2].types) # ["string", "null"]
```
### Multiple TypeDef Definitions
Parse multiple typedef definitions from a single comment block:
```python
jsdoc = '''/**
* @typedef {object} User
* @property {string} name - User's name
*
* @typedef {object} Role
* @property {string} name - Role name
* @property {string[]} permissions - Role permissions
*
* @typedef {string} Status - User status
*/'''
result = parse(jsdoc, include_code=False)
print(len(result.typedefs)) # 3
print(result.typedefs[0].name) # "User"
print(result.typedefs[1].name) # "Role"
print(result.typedefs[2].name) # "Status"
```
Or from separate comment blocks:
```python
jsdoc = '''/**
* @typedef {object} Product
* @property {string} id - Product identifier
* @property {number} price - Product price
*/
/**
* @typedef {object} Category
* @property {string} name - Category name
* @property {Product[]} products - Products in category
*/
function getProducts() {
return products;
}'''
result = parse(jsdoc)
print(len(result.typedefs)) # 2
print(result.typedefs[0].name) # "Product"
print(result.typedefs[1].name) # "Category"
print(result.code) # "function getProducts() { ... }"
```
### Optional Parameters
```python
jsdoc = '''/**
* @param {string} name - Required parameter
* @param {number} [age] - Optional parameter
* @param {string} [email=user@example.com] - Optional with default
*/'''
result = parse(jsdoc, include_code=False)
print(result.params[0].optional) # False
print(result.params[1].optional) # True
print(result.params[2].optional) # True
```
### Union Types
```python
jsdoc = '''/**
* @param {string|number|boolean} value - Multi-type parameter
* @returns {User|null} User object or null
*/'''
result = parse(jsdoc, include_code=False)
print(result.params[0].types) # ["string", "number", "boolean"]
print(result.returns[0].types) # ["User", "null"]
```
### Function Name Extraction
The parser automatically extracts function names from various JavaScript function definition patterns:
```python
# Standard function declaration
jsdoc = '''/**
* A standard function.
*/
function myFunction() {
return true;
}'''
result = parse(jsdoc)
print(result.function_name) # "myFunction"
# Arrow function
jsdoc = '''/**
* An arrow function.
*/
const arrowFunc = () => {
return "hello";
}'''
result = parse(jsdoc)
print(result.function_name) # "arrowFunc"
# Async function
jsdoc = '''/**
* An async function.
*/
async function fetchData() {
return await api.getData();
}'''
result = parse(jsdoc)
print(result.function_name) # "fetchData"
# Class method
jsdoc = '''/**
* A class method.
*/
methodName() {
return this.value;
}'''
result = parse(jsdoc)
print(result.function_name) # "methodName"
```
Supported function definition patterns:
- `function name() {}` - Standard function declarations
- `async function name() {}` - Async function declarations
- `export function name() {}` - Exported functions
- `const name = () => {}` - Arrow functions
- `const name = function() {}` - Function expressions
- `name: function() {}` - Object methods
- `name() {}` - Object method shorthand
- `static name() {}` - Static class methods
## API Reference
### `parse(jsdoc_string: str, include_code: bool = True) -> JSDocComment`
Parse a JSDoc comment string into a structured object.
**Parameters:**
- `jsdoc_string` (str): JSDoc comment string, typically wrapped in `/** */`
- `include_code` (bool): Whether to extract JavaScript code following the comment
**Returns:**
- `JSDocComment`: Structured representation of the parsed JSDoc
**Raises:**
- `ValueError`: If the input is not a valid JSDoc comment format
### Data Models
All returned objects are Pydantic BaseModel instances with full type validation:
- `JSDocComment`: Main container for all parsed data
- `Description`: Comment description with full text and summary
- `Parameter`: Function parameter information
- `ReturnValue`: Return value information
- `TypeDef`: Custom type definition
- `Property`: Object property definition
- `Example`: Usage example
- `Throws`: Exception information
## Error Handling
The parser will raise `ValueError` for invalid input:
```python
try:
result = parse("invalid comment")
except ValueError as e:
print(f"Parse error: {e}")
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/yunfanye/jsdoc
cd jsdoc
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
pytest -v # verbose output
pytest --cov=jsdoc_parser # with coverage
```
### Code Formatting
```bash
black jsdoc_parser/
isort jsdoc_parser/
flake8 jsdoc_parser/
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request
## Changelog
### v1.0.3
- **NEW FEATURE**: Added `function_name` field to automatically extract function names from JavaScript code
- Support for robust function name extraction from various JS function definition patterns:
- Standard function declarations (`function name() {}`)
- Arrow functions (`const name = () => {}`)
- Async functions (`async function name() {}`)
- Exported functions (`export function name() {}`)
- Function expressions (`const name = function() {}`)
- Object methods (`name: function() {}`, `name() {}`)
- Static class methods (`static name() {}`)
- Added comprehensive tests for function name extraction (23 tests total)
- Updated documentation with function name extraction examples
### v1.0.2
- **BREAKING CHANGE**: Changed `typedef` field to `typedefs` (List[TypeDef]) in JSDocComment model
- Added support for multiple typedef definitions in single comment block
- Added support for parsing separate typedef comment blocks
- Improved comment block selection logic for mixed typedef and function documentation
- Enhanced code extraction to work correctly with multiple comment blocks
- Added comprehensive tests for multiple typedef scenarios
- Updated documentation with multiple typedef examples
### v1.0.1
- Bug fixes and improvements
### v1.0.0
- Initial release
- Support for all major JSDoc tags
- Pydantic BaseModel integration
- Comprehensive test suite
- Professional documentation
Raw data
{
"_id": null,
"home_page": null,
"name": "jsdoc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "jsdoc, documentation, parser, javascript",
"author": null,
"author_email": "JSDoc Authors <authors@jsdoc.com>",
"download_url": "https://files.pythonhosted.org/packages/01/5b/302ed58cc04ebef273b531bac1fd3e938ed2cf44148a4e8b89bc6d086398/jsdoc-1.0.3.tar.gz",
"platform": null,
"description": "# JSDoc Parser\n\nA professional Python package for parsing JavaScript documentation comments (JSDoc) into structured Pydantic BaseModel objects.\n\n## Features\n\n- **Comprehensive JSDoc Support**: Parses all major JSDoc tags including `@param`, `@returns`, `@typedef`, `@property`, `@example`, and `@throws`\n- **Multiple TypeDef Support**: Parse multiple `@typedef` definitions from single or separate comment blocks\n- **Type-Safe**: Built with Pydantic BaseModel for robust data validation and type safety\n- **Union Types**: Full support for union types like `string|number|null`\n- **Optional Parameters**: Handles optional parameters with bracket syntax `[param]`\n- **Code Extraction**: Optionally extracts JavaScript code that follows JSDoc comments\n- **Function Name Parsing**: Automatically extracts function names from various JavaScript function definitions\n- **Professional API**: Simple `parse()` function interface with detailed structured output\n\n## Installation\n\n```bash\npip install jsdoc\n```\n\n## Quick Start\n\n```python\nfrom jsdoc import parse\n\n# Parse a JSDoc comment\njsdoc_string = '''/**\n * Adds two numbers together.\n * @param {number} a - The first number\n * @param {number} b - The second number\n * @returns {number} The sum of a and b\n * @example\n * add(1, 2); // returns 3\n */\nfunction add(a, b) {\n return a + b;\n}'''\n\nresult = parse(jsdoc_string)\n\n# Access structured data\nprint(result.description.summary) # \"Adds two numbers together.\"\nprint(result.params[0].name) # \"a\"\nprint(result.params[0].types) # [\"number\"]\nprint(result.returns[0].types) # [\"number\"]\nprint(result.examples[0].code) # \"add(1, 2); // returns 3\"\nprint(result.code) # \"function add(a, b) {\\\\n return a + b;\\\\n}\"\nprint(result.function_name) # \"add\"\n```\n\n## Supported JSDoc Tags\n\n| Tag | Description | Example |\n|-----|-------------|---------|\n| `@param` | Function parameter | `@param {string} name - User's name` |\n| `@returns/@return` | Return value | `@returns {number} Sum of a and b` |\n| `@typedef` | Custom type definition | `@typedef {Object} User` |\n| `@property` | Object property | `@property {number} age - User's age` |\n| `@example` | Usage example | `@example doSomething(123);` |\n| `@throws` | Possible exceptions | `@throws {Error} If input is invalid` |\n\n## Output Structure\n\nThe `parse()` function returns a `JSDocComment` object with the following structure:\n\n```python\n{\n \"description\": {\n \"full\": \"Complete description text...\",\n \"summary\": \"Brief summary sentence.\"\n },\n \"params\": [\n {\n \"types\": [\"string\"],\n \"name\": \"param_name\", \n \"description\": \"Parameter description\",\n \"optional\": False\n }\n ],\n \"returns\": [\n {\n \"types\": [\"number\"],\n \"description\": \"Return value description\"\n }\n ],\n \"examples\": [\n {\n \"code\": \"example_code();\",\n \"description\": None\n }\n ],\n \"throws\": [\n {\n \"types\": [\"Error\"],\n \"description\": \"Exception description\"\n }\n ],\n \"typedefs\": [\n {\n \"types\": [\"Object\"],\n \"name\": \"CustomType\",\n \"description\": \"Type description\",\n \"properties\": [...]\n }\n ],\n \"properties\": [...],\n \"code\": \"function code() { ... }\",\n \"function_name\": \"functionName\",\n \"raw_comment\": \"/** original comment */\"\n}\n```\n\n## Advanced Usage\n\n### Parsing Without Code Extraction\n\n```python\nresult = parse(jsdoc_string, include_code=False)\n# result.code will be None\n```\n\n### Handling TypeDefs with Properties\n\n```python\njsdoc = '''/**\n * @typedef {object} User\n * @property {string} name - User's name\n * @property {number} age - User's age\n * @property {string|null} email - User's email (optional)\n */'''\n\nresult = parse(jsdoc, include_code=False)\nprint(result.typedefs[0].name) # \"User\"\nprint(result.typedefs[0].properties[0].name) # \"name\"\nprint(result.typedefs[0].properties[0].types) # [\"string\"]\nprint(result.typedefs[0].properties[2].types) # [\"string\", \"null\"]\n```\n\n### Multiple TypeDef Definitions\n\nParse multiple typedef definitions from a single comment block:\n\n```python\njsdoc = '''/**\n * @typedef {object} User\n * @property {string} name - User's name\n * \n * @typedef {object} Role\n * @property {string} name - Role name\n * @property {string[]} permissions - Role permissions\n * \n * @typedef {string} Status - User status\n */'''\n\nresult = parse(jsdoc, include_code=False)\nprint(len(result.typedefs)) # 3\nprint(result.typedefs[0].name) # \"User\"\nprint(result.typedefs[1].name) # \"Role\"\nprint(result.typedefs[2].name) # \"Status\"\n```\n\nOr from separate comment blocks:\n\n```python\njsdoc = '''/**\n * @typedef {object} Product\n * @property {string} id - Product identifier\n * @property {number} price - Product price\n */\n\n/**\n * @typedef {object} Category\n * @property {string} name - Category name\n * @property {Product[]} products - Products in category\n */\n\nfunction getProducts() {\n return products;\n}'''\n\nresult = parse(jsdoc)\nprint(len(result.typedefs)) # 2\nprint(result.typedefs[0].name) # \"Product\"\nprint(result.typedefs[1].name) # \"Category\"\nprint(result.code) # \"function getProducts() { ... }\"\n```\n\n### Optional Parameters\n\n```python\njsdoc = '''/**\n * @param {string} name - Required parameter\n * @param {number} [age] - Optional parameter\n * @param {string} [email=user@example.com] - Optional with default\n */'''\n\nresult = parse(jsdoc, include_code=False)\nprint(result.params[0].optional) # False\nprint(result.params[1].optional) # True\nprint(result.params[2].optional) # True\n```\n\n### Union Types\n\n```python\njsdoc = '''/**\n * @param {string|number|boolean} value - Multi-type parameter\n * @returns {User|null} User object or null\n */'''\n\nresult = parse(jsdoc, include_code=False)\nprint(result.params[0].types) # [\"string\", \"number\", \"boolean\"]\nprint(result.returns[0].types) # [\"User\", \"null\"] \n```\n\n### Function Name Extraction\n\nThe parser automatically extracts function names from various JavaScript function definition patterns:\n\n```python\n# Standard function declaration\njsdoc = '''/**\n * A standard function.\n */\nfunction myFunction() {\n return true;\n}'''\nresult = parse(jsdoc)\nprint(result.function_name) # \"myFunction\"\n\n# Arrow function\njsdoc = '''/**\n * An arrow function.\n */\nconst arrowFunc = () => {\n return \"hello\";\n}'''\nresult = parse(jsdoc)\nprint(result.function_name) # \"arrowFunc\"\n\n# Async function\njsdoc = '''/**\n * An async function.\n */\nasync function fetchData() {\n return await api.getData();\n}'''\nresult = parse(jsdoc)\nprint(result.function_name) # \"fetchData\"\n\n# Class method\njsdoc = '''/**\n * A class method.\n */\nmethodName() {\n return this.value;\n}'''\nresult = parse(jsdoc)\nprint(result.function_name) # \"methodName\"\n```\n\nSupported function definition patterns:\n- `function name() {}` - Standard function declarations\n- `async function name() {}` - Async function declarations \n- `export function name() {}` - Exported functions\n- `const name = () => {}` - Arrow functions\n- `const name = function() {}` - Function expressions\n- `name: function() {}` - Object methods\n- `name() {}` - Object method shorthand\n- `static name() {}` - Static class methods\n\n## API Reference\n\n### `parse(jsdoc_string: str, include_code: bool = True) -> JSDocComment`\n\nParse a JSDoc comment string into a structured object.\n\n**Parameters:**\n- `jsdoc_string` (str): JSDoc comment string, typically wrapped in `/** */`\n- `include_code` (bool): Whether to extract JavaScript code following the comment\n\n**Returns:**\n- `JSDocComment`: Structured representation of the parsed JSDoc\n\n**Raises:**\n- `ValueError`: If the input is not a valid JSDoc comment format\n\n### Data Models\n\nAll returned objects are Pydantic BaseModel instances with full type validation:\n\n- `JSDocComment`: Main container for all parsed data\n- `Description`: Comment description with full text and summary\n- `Parameter`: Function parameter information\n- `ReturnValue`: Return value information \n- `TypeDef`: Custom type definition\n- `Property`: Object property definition\n- `Example`: Usage example\n- `Throws`: Exception information\n\n## Error Handling\n\nThe parser will raise `ValueError` for invalid input:\n\n```python\ntry:\n result = parse(\"invalid comment\")\nexcept ValueError as e:\n print(f\"Parse error: {e}\")\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/yunfanye/jsdoc\ncd jsdoc\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\npytest -v # verbose output\npytest --cov=jsdoc_parser # with coverage\n```\n\n### Code Formatting\n\n```bash\nblack jsdoc_parser/\nisort jsdoc_parser/\nflake8 jsdoc_parser/\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for your changes\n4. Ensure all tests pass\n5. Submit a pull request\n\n## Changelog\n\n### v1.0.3\n- **NEW FEATURE**: Added `function_name` field to automatically extract function names from JavaScript code\n- Support for robust function name extraction from various JS function definition patterns:\n - Standard function declarations (`function name() {}`)\n - Arrow functions (`const name = () => {}`)\n - Async functions (`async function name() {}`)\n - Exported functions (`export function name() {}`)\n - Function expressions (`const name = function() {}`)\n - Object methods (`name: function() {}`, `name() {}`)\n - Static class methods (`static name() {}`)\n- Added comprehensive tests for function name extraction (23 tests total)\n- Updated documentation with function name extraction examples\n\n### v1.0.2\n- **BREAKING CHANGE**: Changed `typedef` field to `typedefs` (List[TypeDef]) in JSDocComment model\n- Added support for multiple typedef definitions in single comment block\n- Added support for parsing separate typedef comment blocks\n- Improved comment block selection logic for mixed typedef and function documentation\n- Enhanced code extraction to work correctly with multiple comment blocks\n- Added comprehensive tests for multiple typedef scenarios\n- Updated documentation with multiple typedef examples\n\n### v1.0.1\n- Bug fixes and improvements\n\n### v1.0.0\n- Initial release\n- Support for all major JSDoc tags\n- Pydantic BaseModel integration\n- Comprehensive test suite\n- Professional documentation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for parsing JSDoc comment blocks into structured BaseModel objects",
"version": "1.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/yunfanye/jsdoc/issues",
"Documentation": "https://github.com/yunfanye/jsdoc",
"Homepage": "https://github.com/yunfanye/jsdoc",
"Repository": "https://github.com/yunfanye/jsdoc.git"
},
"split_keywords": [
"jsdoc",
" documentation",
" parser",
" javascript"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d4c49b0fa82c52c796954de52492e3cf9c1f46b3f176db477520b325201c8042",
"md5": "1b479dab10a9e3ad99fefcc2aabfade3",
"sha256": "77c1fcc277951ebe1c28da1445f0d436aa0f4d9a86807356fce0e5c531e76e06"
},
"downloads": -1,
"filename": "jsdoc-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b479dab10a9e3ad99fefcc2aabfade3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11403,
"upload_time": "2025-07-27T02:22:42",
"upload_time_iso_8601": "2025-07-27T02:22:42.098681Z",
"url": "https://files.pythonhosted.org/packages/d4/c4/9b0fa82c52c796954de52492e3cf9c1f46b3f176db477520b325201c8042/jsdoc-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "015b302ed58cc04ebef273b531bac1fd3e938ed2cf44148a4e8b89bc6d086398",
"md5": "73a34449b64a9e3f8d8bc4148272677e",
"sha256": "2e75af4fcb8095922e0443ca2033088cb6e4316f0d468f032202964ac555513d"
},
"downloads": -1,
"filename": "jsdoc-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "73a34449b64a9e3f8d8bc4148272677e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20378,
"upload_time": "2025-07-27T02:22:42",
"upload_time_iso_8601": "2025-07-27T02:22:42.863571Z",
"url": "https://files.pythonhosted.org/packages/01/5b/302ed58cc04ebef273b531bac1fd3e938ed2cf44148a4e8b89bc6d086398/jsdoc-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 02:22:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yunfanye",
"github_project": "jsdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsdoc"
}
