{"id":13626379,"url":"https://github.com/syavorsky/comment-parser","last_synced_at":"2026-02-21T12:46:58.082Z","repository":{"id":14834806,"uuid":"17557665","full_name":"syavorsky/comment-parser","owner":"syavorsky","description":"Generic JSDoc-like comment parser.","archived":false,"fork":false,"pushed_at":"2026-01-22T20:10:05.000Z","size":1254,"stargazers_count":259,"open_issues_count":15,"forks_count":25,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-17T18:41:09.229Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syavorsky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-03-09T04:24:52.000Z","updated_at":"2026-02-14T16:16:07.000Z","dependencies_parsed_at":"2026-01-03T11:07:34.399Z","dependency_job_id":null,"html_url":"https://github.com/syavorsky/comment-parser","commit_stats":{"total_commits":290,"total_committers":19,"mean_commits":"15.263157894736842","dds":0.503448275862069,"last_synced_commit":"a9092770e24bb65b965b93d2c7d7b53608511975"},"previous_names":["yavorskiy/comment-parser"],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/syavorsky/comment-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syavorsky%2Fcomment-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syavorsky%2Fcomment-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syavorsky%2Fcomment-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syavorsky%2Fcomment-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syavorsky","download_url":"https://codeload.github.com/syavorsky/comment-parser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syavorsky%2Fcomment-parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29609627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T06:47:36.664Z","status":"ssl_error","status_checked_at":"2026-02-19T06:45:47.551Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:02:16.697Z","updated_at":"2026-02-21T12:46:58.066Z","avatar_url":"https://github.com/syavorsky.png","language":"TypeScript","readme":"# comment-parser\n\n`comment-parser` is a library helping to handle Generic JSDoc-style comments. It is\n\n- **language-agnostic** – no semantics enforced. You decide what tags are and what they mean. And it can be used with any language supporting `/** */` source comments.\n- **no dependencies** – it is compact and environment-agnostic, can be run on both the server and browser sides\n- **highly customizable** – with a little code you can deeply customize how comments are parsed\n- **bidirectional** - you can write comment blocks back to the source after updating or formatting\n- **strictly typed** - comes with generated `d.ts` data definitions since written in TypeScript\n\n```sh\nnpm install comment-parser\n```\n\n\u003e 💡 Check out the [Playground](https://syavorsky.github.io/comment-parser)\n\n\u003e 💡 Previous version lives in [0.x](https://github.com/syavorsky/comment-parser/tree/0.x) branch\n\nLib mainly provides two pieces [Parser](#Parser) and [Stringifier](#Stringifier).\n\n## Parser\n\nLet's go over string parsing:\n\n```js\nconst { parse } = require('comment-parser/lib')\n\nconst source = `\n/**\n * Description may go\n * over few lines followed by @tags\n * @param {string} name the name parameter\n * @param {any} value the value of any type\n */`\n\nconst parsed = parse(source)\n```\n\nLib source code is written in TypeScript and all data shapes are conveniently available for your IDE of choice. All types described below can be found in [primitives.ts](src/primitives.ts)\n\nThe input source is first parsed into lines, then lines split into tokens, and finally, tokens are processed into blocks of tags\n\n### Block\n\n```js\n/**\n * Description may go\n * over multiple lines followed by @tags\n * @param {string} name the name parameter\n * @param {any} value the value parameter\n */\n```\n\n### Description\n\n```js\n/**\n * Description may go\n * over multiple lines followed by @tags\n```\n\n### Tags\n\n```js\n * @param {string} name the name parameter\n```\n\n```js\n * @param {any} value the value parameter\n */\n```\n\n### Tokens\n\n```\n|line|start|delimiter|postDelimiter|tag   |postTag|name |postName|type    |postType|description                     |end|\n|----|-----|---------|-------------|------|-------|-----|--------|--------|--------|--------------------------------|---|\n|   0|{2}  |/**      |             |      |       |     |        |        |        |                                |   |\n|   1|{3}  |*        |{1}          |      |       |     |        |        |        |Description may go              |   |\n|   2|{3}  |*        |{1}          |      |       |     |        |        |        |over few lines followed by @tags|   |\n|   3|{3}  |*        |{1}          |@param|{1}    |name |{1}     |{string}|{1}     |the name parameter              |   |\n|   4|{3}  |*        |{1}          |@param|{1}    |value|{1}     |{any}   |{1}     |the value of any type           |   |\n|   5|{3}  |         |             |      |       |     |        |        |        |                                |*/ |\n```\n\n### Result\n\nThe result is an array of Block objects, see the full output on the [playground](https://syavorsky.github.io/comment-parser)\n\n```js\n[{\n  // uppper text of the comment, overall block description\n  description: 'Description may go over multiple lines followed by @tags',\n  // list of block tags: @param, @param\n  tags: [{\n    // tokens.tag without \"@\"\n    tag: 'param',\n    // unwrapped tokens.name\n    name: 'name',\n    // unwrapped tokens.type\n    type: 'string',\n    // true, if tokens.name is [optional]\n    optional: false,\n    // default value if optional [name=default] has one\n    default: undefined,\n    // tokens.description assembled from a siongle or multiple lines\n    description: 'the name parameter',\n    // problems occured while parsing this tag section, subset of ../problems array\n    problems: [],\n    // source lines processed for extracting this tag, \"slice\" of the ../source item reference\n    source: [ ... ],\n  }, ... ],\n  // source is an array of `Line` items having the source\n  // line number and `Tokens` that can be assembled back into\n  // the line string preserving original formatting\n  source: [{\n    // source line number\n    number: 1,\n    // source line string\n    source: \"/**\",\n    // source line tokens\n    tokens: {\n      // indentation\n      start: \"\",\n      // delimiter, either '/**', '*/', '*', or ''. Mid lines may have no delimiters\n      delimiter: \"/**\",\n      // space between delimiter and tag\n      postDelimiter: \"\",\n      // tag starting with \"@\"\n      tag: \"\",\n      // space between tag and type\n      postTag: \"\",\n      // name with no whitespaces or \"multiple words\" wrapped into quotes. May occure in [name] and [name=default] forms\n      name: \"\",\n      // space between name and type\n      postName: \"\",\n      // type is has to be {wrapped} into curlies otherwise will be omitted\n      type: \"\",\n      // space between type and description\n      postType: \"\",\n      // description is basicaly rest of the line\n      description: \"\",\n      // closing */ marker if present\n      end: \"\"\n    }\n  }, ... ],\n  // problems occured while parsing the block\n  problems: [],\n}];\n```\n\nWhile `.source[].tokens` are not providing readable annotation information, they are essential for tracing data origins and assembling string blocks with `stringify`\n\n### options\n\n```ts\ninterface Options {\n  // start count for source line numbers\n  startLine: number;\n  // escaping chars sequence marking wrapped content literal for the parser\n  fence: string;\n  // block and comment description compaction strategy\n  spacing: 'compact' | 'preserve';\n  // tokenizer functions extracting name, type, and description out of tag, see Tokenizer\n  tokenizers: Tokenizer[];\n}\n```\n\nexamples\n- [default config](https://syavorsky.github.io/comment-parser/#parse-defaults)\n- [line numbers control](https://syavorsky.github.io/comment-parser/#parse-line-numbering)\n- [description spacing](https://syavorsky.github.io/comment-parser/#parse-spacing)\n- [escaping](https://syavorsky.github.io/comment-parser/#parse-escaping)\n- [explore the origin source](https://syavorsky.github.io/comment-parser/#parse-source-exploration)\n\n[suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...\u0026labels=example,parser)\n\n## Stringifier\n\nThe stringifier is an important piece used by other tools updating the source code. It goes over `Block.source[].tokens` items and assembles them back to the string. It might be used with various transforms applied before stringifying.\n\n```js\nconst { parse, stringify, transforms: {flow, align, indent} } = require('comment-parser');\n\nconst source = `\n  /**\n   * Description may go\n   * over multiple lines followed by @tags\n   *\n* @my-tag {my.type} my-name description line 1\n      description line 2\n    * description line 3\n   */`;\n\nconst parsed = parse(source);\nconst transform = flow(align(), indent(0))\nconsole.log(stringify(transform(parsed[0])));\n```\n\n### Result\n\n```js\n/**\n * Description may go\n * over multiple lines followed by @tags\n *\n * @my-tag {my.type} my-name description line 1\n                             description line 2\n *                           description line 3\n */\n```\n\nexamples\n- [format comments](https://syavorsky.github.io/comment-parser/#stringify-formatting)\n\n[suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...\u0026labels=example,stringifier)\n\n## Migrating from 0.x version\n\nCode of pre-1.0 version is forked into [0.x](https://github.com/syavorsky/comment-parser/tree/0.x) and will phase out eventually. Please file the issue if you find some previously existing functionality can't be achieved with 1.x API. Check out [migration notes](migrate-1.0.md).\n","funding_links":[],"categories":["Parsing and Stringifying","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyavorsky%2Fcomment-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyavorsky%2Fcomment-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyavorsky%2Fcomment-parser/lists"}