mdconf-style tags

[tmcw]

In drafting up the spec and testing out some code examples in CommonMark, I'm really liking the approach of mdconf's tags: instead of

// @param a {string}
// @param b {string}
function b(a, b) {}

It'd be

// - param: a {string}
// - param: b {string}
function b(a, b) {}

Advantages being:

• @param will no longer send a github notification to poor @param every time someone posts it in an issue
• Multiple tags inline look correct through a CommonMark parser, whereas the JSDoc syntax has them smooshed onto one line

[tmcw]

Thoughts: how do we differentiate between these lists of structured data and unstructured lists that are part of the description? For instance:

// wow what a great method we have here
// it does a bunch of things like
// - slices
// - dices
//
// - param: a {string}
// - param: b {string}
function b(a, b) {}

[tmcw]

Considerations:

mdconf isn't going to be the savior here: the implementation is pretty tolerant/unpredictable

console.log(JSON.stringify(parse(`# Test

- a: 1
- b: 2`), null, 2));

-> {
  "test": {
    "a": "1",
    "b": "2"
  }
}

console.log(JSON.stringify(parse(`# Test

- a: 1
- b: 2
- c`), null, 2));

-> {
  "test": [
    "c"
  ]
}

Going to write a stricter implementation. Optional params should be settable as just true, due to how tags like deprecated should work.

[jamiebuilds]

I would take inspiration from TOML