cmtdoc-parser v1.1.12
Comment Doc Parser
A Node.js library to parse documentation comments. This is a simple library that allows you to parse documentation from one comment. This module made for parse documentation comments in DPAG template files dedicated DBPAGES web application server.
Install via npm
npm install cmtdoc-parserLibrary usage
Describe supported figures
const cmtDocParser = require('cmtdoc-parser');
console.log(cmtDocParser.describe());or
npm run describeThe result will be something like this
You can also refer to the DESCRIBE.md file for information about figures.
...
Figure: @version version description
Documents the version number of an item.
Kind: property of string
Example:
@version 1.0.45
@version 0.0.1 Beta
Result:
{
"version": "0.0.1 Beta"
}
Figure: @todo text describing thing to do.
Document tasks to be completed.
Kind: array of string
Example:
@todo Write the documentation.
@todo Implement this function.
Result:
{
"todos": [
"Write the documentation.",
"Implement this function."
]
}
Figure: @see [{@link namepath}|namepath] [description]
Refer to some other documentation for more information.
Kind: array of object
Example:
@see {@link bar}
@see bar
@see {@link foo} for further information.
@see {@link http://github.com|GitHub}
@see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
@see package.Class#method(Type argname, Type argname,...)
Result:
{
"see": [
{
"path": "{@link bar}"
},
{
"path": "bar"
},
{
"path": "{@link foo}",
"description": "for further information."
},
{
"path": "{@link http://github.com|GitHub}"
},
{
"description": "<a href=\"http://www.link_to_jira/HERO-402\">HERO-402</a>"
},
{
"path": "package.Class#method(Type argname, Type argname,...)"
}
]
}
...Parse single documentation comment
const cmtDocParser = require('cmtdoc-parser');
console.log(cmtDocParser.parse(`/**
* Parse single documentary comment
*
* I used the resources from the website https://jsdoc.app/ and prepared the regex using the website https://regex101.com/
*
* @author Andrzej Kałuża
* @created 2025-01-16
* @version 1.0.0
* @module cmtdoc-parser
*/`)
);The result will be something like this
{
description: 'Parse single documentary comment\n' +
'\n' +
'I used the resources from the website https://jsdoc.app/ and prepared the regex using the website https://regex101.com/',
author: { author: 'Andrzej Kałuża' },
created: '2025-01-16',
module: { name: 'cmtdoc-parser' },
version: '1.0.0'
}Extensions usage
Parse single file
This is a simple function that finds and processes comments documenting in file. This function add property "under" for each found comment for future parse.
const cmtDocParser = require('cmtdoc-parser');
require('cmtdoc-parser/extensions/parse-file');
console.log(JSON.stringify(cmtDocParser.parseFile("cmtdoc-parser/index.js", { under : { name : true } }), null, "\t"));The result will be something like this
[
{
"description": "A simple function that finds and processes comments documenting in file\n\nThis function add property under for each found comment for future parse",
"parameters": [
{
"type": "string",
"name": "path",
"description": "path with filename",
"types": [
"string"
]
},
{
"type": "json",
"name": "options",
"types": [
"json"
]
}
],
"properties": [
{
"type": "boolean",
"name": "options.under.code",
"description": "returns code founded under comment",
"types": [
"boolean"
]
},
{
"type": "boolean",
"name": "options.under.name",
"description": "returns code founded/parsed name under comment",
"types": [
"boolean"
]
},
{
"type": "boolean",
"name": "options.matches",
"description": "include matches in documentation structure",
"types": [
"boolean"
]
}
],
"returns": {
"type": "json[]",
"description": "array of documentation structures",
"types": [
"json[]"
]
},
"under": {
"name": "parseFile"
}
}
]Platforms usage
PostgreSQL
Run script platforms/postgresql.js to generate PostgreSQL function parsing jsdoc
npm run postgresql -- out=platforms/postgresql.sql function=jsdoc_parseor
node postgresql out=platforms/postgresql.sql function=jsdoc_parseAs a result you will get jsdoc_parse function in postgresql.sql file to be store in database. Like below...
create or replace function jsdoc_parse(str varchar) returns jsonb language plpgsql stable
as $fn$
begin
str := string_agg(substring(line from '^\s*\*\s*(.*)'), e'\n')
from (select unnest(string_to_array(str, e'\n')) line) d
where trim(line) not in ('/**', '*/');
--
return jsonb_object_agg(r.figure, r.object)
from ( -- This is root description
select 'root' as figure, to_jsonb(r[1]) as object
from regexp_matches(str, '^([^@]+)') r
union all
...
-- @callback name
select 'callback' as figure, to_jsonb(array_agg(r[3])) as object
from regexp_matches(str, '@(callback)(\s+([^\s@]+))', 'g') r
having array_agg(r[3]) is not null) r;
end;
$fn$;You can use it by executing the query below. I assume that the functions have the js comment contained in the function body, not in the function comment.
select p.proname, jsdoc_parse(p.doc) as doc, p.arguments, p.description
from (select p.proname, substring(pg_get_functiondef(p.oid) from '\/\*\*.*\*\/') as doc,
coalesce(pg_get_function_arguments(p.oid), '') arguments,
d.description
from pg_proc p
join pg_namespace n on n.oid = p.pronamespace
left join pg_description d on d.classoid = 'pg_proc'::regclass and d.objoid = p.oid and d.objsubid = 0
where n.nspname = :scema_name
and p.prokind in ('p', 'f')) p
where p.doc is not nullOn a server (24 cores) Postgres 9.6, in a schema with 1600 functions, 450 of which have comments, the query was completed in 1-2 seconds. On a server (4 cores) Postgre 15, in a schema with 40 functions, 30 of which have comments, the query was completed < 100ms.