More detailed markdown template

[simonauner]

Let me start off by saying that I am impressed with how smooth documentationjs works. I started fiddling around with it the other day and it's really impressive, especially to be able to output directly to a README.md.

I would like to suggest an improvement to the markdown template. The improvement mainly serves two functions:

1. Make it easier to distinguish functions from fields or constants, currently there's no visible difference between a @constant, @function or @event
2. More information density in the function header

When generating html docs from the following code:

/**
 * Gets user data. If forceReload is provided it will force check from backend, otherwise it will use locally cached data.
 * @param  {Object} options
 * @param  {Boolean} [options.forceReload=false] Force reload from server, otherwise uses local cache
 * @return {Promise} Promise with user data if success, failure reason otherwise
 */
function getData(options) {
...
}

this is the result:

This is the benchmark ☝️ When generating to markdown this is the result:

---

getData

Gets user data. If forceReload is provided it will force check from backend, otherwise it will use locally cached data.

Parameters

• options Object
  • options.forceReload [Boolean] Force reload from server, otherwise uses local cache (optional, default false)

Returns Promise Promise with user data if success, failure reason otherwise

---

I suggest to improve it to:

---

getData(options: Object): Promise

Gets user data. If forceReload is provided it will force check from backend, otherwise it will use locally cached data.

Parameters

• options Object
  • options.forceReload [Boolean] Force reload from server, otherwise uses local cache (optional, default false)

Returns Promise Promise with user data if success, failure reason otherwise

---

If this seems like a reasonable improvement to you I can try to fix it myself with a PR if I could be pointed in the right direction.

[tmcw]

Thanks! And, yep, I agree with this direction for an improvement.

The Markdown output is generated by transforming comments into a Markdown AST, which gets stringified all at once with wooorm/remark. Here's the line that generates the title line of a documentation block in Markdown.

Right now the generation of the header you suggest is what we call a 'signature' and is generated in this part of the default theme. If we use signatures in Markdown too, we'd want to move it out of the theme and into lib/.

Happy to answer any questions you have about ^ code!

[simonauner]

Thanks. I'm currently working on a PR, but it takes time to get my head around the markdown AST and to make sure it doesn't create unnecessary HTML when creating the util which is to be used by both the default HTML template and the Markdown renderer.

[tmcw]

The AST can be tricky! The mdast API documentation can be of some help - it includes every possible node that can occur in the AST and which other nodes it can include.

[wooorm]

@simonauner Hi! 👋 I made mdast, and hope you find the docs useful. Please do let me know if you have a suggestions or questions!

[simonauner]

Hi and thanks for reaching out @wooorm! I'll make sure to note if any improvements can be made, I'm quite sure that it's mostly me not being used to the format and syntax.

Maybe I can link my fork later this week and you can have a look to see if I have understood it properly.

[wooorm]

Sure thing, Simon!