Custom tags

[kasperlewau]

I've looked through previous issues as well as the docs, but I can't find anything related to custom tags.

I've had a go at passing through a jsdoc.json config file to the linter but it does not seem as though it reads JSDoc configuration.

/** 
  * @namespace humdidum
  * @ngInject 
  */
export default ($eek, $stringBasedDI) => {
 // redacted
}

The linter will correctly identify ngInject and call it out for being an unknown JSDoc tag.

[tmcw]

Hi Kasper,

I've had a go at passing through a jsdoc.json config file to the linter but it does not seem as though it reads JSDoc configuration.

Yep, that's correct - documentation.js doesn't currently support jsdoc.json. It supports JSDoc syntax for comments, but isn't a swap-in replacement for JSDoc.

Could you say a bit more about the intent of ngInject? Do you want it to produce some output on the documentation side, or have some other meaning? Is it part of any existing documentation specification?

Thanks,

• Tom

[demsking]

Same question: How to create a custom tag which works like @module for instance?

/** 
  * @component MyComponent
  * @slot default - A default slot
  * @slot title - A title slot
  */
export default {
}

[tmcw]

I'm still not completely clear on the intent here - of your or Kasper's suggestions. What would component do? How would it be different than @module? How would @slot work? Are these JavaScript concepts we're representing, or something higher-level?

I'm more than happy to discuss this further - currently the ideas around what custom tags are and what they do, or produce in documentation - are too vague for me to really act upon.

[demsking]

Custom tags feature are interesting to documented a specific framework for instance. So I should be able to document a Vue Component with its own terms for instance.

[kasperlewau]

@tmcw Sorry for the delay from my end.

Essentially what I'm looking for is a whitelist of known-unknowns so as to not make the documentation linter scream about tags I intentionally put in there for other systems/tools to work as expected.

I should've put this in the OP.

// foo.js 

/**
 * I sorely want to be linted. 
 * @param {string} a
 * @nginject
 */
export default function (a) {
}

$ documentation lint --known-unknowns nginject foo.js

[tehvgg]

As @kasperlewau said, being able to define a list of custom tags (or "true" to allow all) as JSDoc has done here would be greatly beneficial.

I want to add a @codepen tag, where I can link to a pen that I would embed in my documentation with a custom theme.

/**
 * @codepen http://codepen.io/user/embed/pen_id
 * @param [foo] - ...
 */
function bar (foo) { ... }

[Telokis]

@tmcw After reading this part 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 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 and jsdoc with its 9 events.)

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:

{
    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)

I opened a new issue for a complete plugin system here: #1125