Provide a way to attach custom data to documentation nodes

[anandthakker]

Quoting from https://github.com/tmcw/dx-spec/issues/23#issuecomment-348857662

I'm honestly not sure if there should be a "fires" since there's no standard event emitter in every environment

This is a good point: there's no standard event emitter, but event-based APIs are ubiquitous. If I were to use dx, I would definitely need a way to attach @fires-like data to a method. In the case of events, I think I'm personally in favor of keeping fires, but this raises a broader point: should dx afford users to include arbitrary tags beyond those that are reserved by the spec?

This would give users a workaround in cases like fires if we choose to omit it from the core spec. It also gives us a 'release valve' to more easily resist creep in the spec as needs for new tags crop up over time. I myself could see using this for things like having a structured way to mark a method const (or to document other kinds of invariants consistently).

[tmcw]

prev: documentation.js - https://github.com/documentationjs/documentation/issues/683

I've been uncomfortable with the idea of custom tags in documentation.js for a number of reasons:

• if we're loose about tags and allow arbitrary custom tags, then our ability to validate is greatly reduced, because typos become valid
• the examples that i've seen so far - like a custom tag called @component don't just mean custom data but custom behavior on the part of the documentation tool, and I don't see any clear route to allowing the right amount of custom behavior.
• If custom tags are available, should they all follow the same syntax (something like - tag: {type} description, or a different syntax? Are syntaxes something you should be able to choose?

I'm in favor of supporting some sort of additional data for the reasons you note - that it's an escape hatch for spec creep. And I shouldn't expect people coming to the d.js issue tracker to have fully-formed thoughts about implementation and spec. Heck, in the 'custom tag' case that was initially proposed, @ngInject, the tag doesn't have any documentation meaning - it's a trigger for the minification step of angular build processes, that some lil' trickster used JSDoc-like syntax for, for who knows no reason.

At least this morning, I wonder about having custom data as a possibility, not custom tags. Completely remove the expectations of tags, and just say "well, you can throw some structured data in this comment and it will appear at the theme stage" with zero guarantees beyond that, and no involvement with inference or structure. Maybe even a separate part of the documentation comment for custom tags, or a different-enough syntax, like - _fires:_Eventsome event as a way of making it clearly not a standard tag. That way we could avoid having a configuration file for customs, keep parsing strict, and make custom tags obviously different in documentation comments.

[anandthakker]

At least this morning, I wonder about having custom data as a possibility, not custom tags. Completely remove the expectations of tags, and just say "well, you can throw some structured data in this comment and it will appear at the theme stage" with zero guarantees beyond that, and no involvement with inference or structure.

💯 yeah, I think this makes more sense than custom tags. Retitling issue to be about the underlying need for custom data -- 'custom tags' is one way to address that need, but I agree that it's pretty problematic because of the issues you raised above.

[jamiebuilds]

I was already thinking that we should have a TOML/YAML-like syntax for various things:

/*
 * - meta:
 *   foo: str
 *   bar: 2
 *   baz: true
 */

[jamiebuilds]

I would also be fine if we had an API where you could explicitly provide your own tags which would overwrite built-ins so there isn't conflicts if we add new ones in the future.

{
  "name": "package",
  "version": "1.2.3",
  "main": "src/index.js",
  "devDependencies": {
    "dx": "^1.0.0"
  },
  "dx": {
    "customTags": {
      "fires": "list",
      "injects": "list",
      "provides": "string"
    }
  }
}

[jamiebuilds]

That could actually be really interesting if we had framework presets which could extend tags/parsing/rendering:

{
  "name": "package",
  "version": "1.2.3",
  "main": "src/index.js",
  "devDependencies": {
    "@dx/core": "^1.0.0",
    "@dx/angular": "^1.0.0",
  },
  "dx": {
    "extends": ["@dx/angular"]
  }
}