https://github.com/SlimIO/jsdoc
Blazing fast 🚀 JSDoc generator/parser
https://github.com/SlimIO/jsdoc
Last synced: 15 days ago
JSON representation
Blazing fast 🚀 JSDoc generator/parser
- Host: GitHub
- URL: https://github.com/SlimIO/jsdoc
- Owner: SlimIO
- License: mit
- Created: 2019-03-27T06:33:54.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2021-07-26T04:51:02.000Z (over 3 years ago)
- Last Synced: 2025-03-25T02:15:50.446Z (21 days ago)
- Language: JavaScript
- Homepage:
- Size: 86.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-blazingly-fast - jsdoc - Blazing fast 🚀 JSDoc generator/parser (JavaScript)
README
# jsdoc
[](https://github.com/SlimIO/jsdoc/commit-activity)
[](https://snyk.io//test/github/SlimIO/jsdoc?targetFile=package.json)
[](https://travis-ci.com/SlimIO/jsdoc)
JSDoc Generator/Parser. (It use [jsdoc-extractor](https://github.com/fraxken/jsdoc-extractor) and [jsdoc-tokenizer](https://github.com/fraxken/jsdoc-tokenizer) under the hood).
## Requirements
- [Node.js](https://nodejs.org/en/) v12 or higher
## Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @slimio/jsdoc
# or
$ yarn add @slimio/jsdoc
```
## Usage example
The method will search all JavaScript files at the given location to parse the inner JSDoc.
```js
const { parseFile, groupData } = require("@slimio/jsdoc");
async function main() {
const fileBlocks = [];
for await (const block of parseFile("./yourFile.js")) {
fileBlocks.push(block);
}
const finalResult = groupData(fileBlocks);
console.log(JSON.stringify(finalResult, null, 4));
}
main().catch(console.error);
```
## API
parseJSDoc(buf: Buffer): Block
Parse a JSDoc block (in Buffer format). Return an Object described by the following interface:
```ts
interface Descriptor {
value: any;
name?: string;
desc?: string;
default?: any;
required?: boolean;
}
interface Block {
[key: string]: Descriptor | Descriptor[];
}
```
Take the following example:
```js
const block = parseJSDoc(Buffer.from(`/**
@const name
@type {String}
**/`));
console.log(block.const.value); // name
console.log(block.type.value); // String
```
parseFile(location: string): AsyncIterableIterator< Block >
This method will read a given file, extract and parse all JSDoc blocks. The method return a Asynchronous iterator to be able to stop the parsing at any time.
```js
const jsdoc = [];
const iterator = parseFile("./yourFile.js");
for await (const block of iterator) {
jsdoc.push(block);
}
```
groupData(blocks: Block[]): LinkedBlock
Link (group) blocks by **namespace**, **modules** or **class** (Else the block will be handled as an orphan). The method return an Object described by the following interface:
```ts
interface LinkedBlock {
orphans: Block[];
members: {
[name: string]: Block[];
}
}
```
## Dependencies
|Name|Refactoring|Security Risk|Usage|
|---|---|---|---|
|[jsdoc-extractor](https://github.com/fraxken/jsdoc-extractor#readme)|⚠️Major|Low|Extract JSDoc annotations from Javascript Files|
|[jsdoc-tokenizer](https://github.com/fraxken/jsdoc_tokenizer#readme)|⚠️Major|Low|Parse JSDoc annotations and return Tokens|
## License
MIT