Recommend minimum ingredient combinations

[tmcw]

trafficstars

[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:_ Event some 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"]
  }
}