documentationjs / documentationjs/documentation

Adding a complete plugin system

Open
#1,125 3 comments 6 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

(Followup to #683)

After reading [this part](https://github.com/documentationjs/documentation/blob/master/docs/FAQ.md#why-use-documentation-instead-of-jsdoc) of the FAQ, I thought that documentationjs had a "well documented and flexible" plugin system because it said `Customization points like plugins & templates are well documented and flexible`.
What I expect from a plugin is to be able to fully alter any step of the generation process. From the config reading to after the files have been written. (As can provide [esdoc with its 10 callbacks](https://esdoc.org/manual/api.html) and [jsdoc with its 9 events](http://usejsdoc.org/about-plugins.html).)

Here is a very concrete example:
I am currently working on a NodeJS web server. I have a lot of classes, functions, etc that are documented using jsdoc style comments but I would also like to have a custom `@route {GET} /users` tag that would attach specific informations to the AST.
To achieve this, I would "simply" create a plugin, make it listen for some kind of `onDocTag` event where `tag === "route"` and attach some additional properties to the doc node:
```js
{
kind: "route",
method: "GET",
path: "/users"
}
```

Then, later in my plugin, I would be able to alter the generated output by adding some kind of "meta format tag" in order to have specific formatting of my routes.

I hope this use case is clear enough because it's a very real thing I'd like to be able to do.

(I am not looking for a workaround, I'd really like to have custom tags handled by the plugin defining them)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.