jsdoc2md
Fix: es6 constructor docs generation (fixes #33)
This fixes addresses the linked issue:
/**
* @class LinkedList
*
* @example
* const linkedList = new LinkedList();
*/
class LinkedList {
jsdoc-parse currently ignores the example in this scenario -- it only outputs constructor documentation if a description or param tags are present. With this change it checks for example tags as well.
I now remember why the @example tag was excluded from the class. What happens if you also include a constructor example, like this?
/**
* @class Example
*
* @example
* const linkedList = new LinkedList()
*/
class Example {
/**
* @example
* const whatAbout = 'this'
*/
constructor () {
/**
* An instance variable
*/
this.one = 'something'
}
}
With your patch, everything is duplicated (see below). The reason for this is because with ES5, there was only one place to write a constructor example - in the docs above the constructor function. Now, in ES6 there are potentially two places to write a constructor example - above the class statement and above the constructor statement.
Example
Kind: global class
- Example
- new Example()
- new Example()
- .one
new Example()
Example
const linkedList = new LinkedList()
new Example()
Example
const whatAbout = 'this'
example.one
An instance variable
Kind: instance property of Example
Example
Kind: global class
- Example
- new Example()
- new Example()
- .one
new Example()
Example
const linkedList = new LinkedList()
new Example()
Example
const whatAbout = 'this'
example.one
An instance variable
Kind: instance property of Example
Jsdoc2md has a convention: always write constructor docs (examples etc) in the documentation above the constructor statement, not the class. Try rewriting your docs like this:
/**
* @class LinkedList
*/
class LinkedList {
/**
* @example
* const linkedList = new LinkedList();
*/
constructor () { }
}
Does that solve your issue?
Sorry, I forgot to mention a description is required. There is a reason for this, possibly (sorry it was years ago when I wrote it) that the output markdown looks broken without it. You'll need to write this:
/**
* @class LinkedList
*/
class LinkedList {
/**
* Description required.
* @example
* const linkedList = new LinkedList();
*/
constructor () { }
}
With your patch, everything is duplicated
I'm not seeing this behavior on my end. Just to clarify, was it your expectation that the examples would be duplicated, or were the docs you posted above actually generated from the code example?
Without the patch the following code
/**
* some description
* @class
* @example
* const list = new LinkedList();
*/
class LinkedList {
/**
* some description
* @example
* const secondList = new LinkedList();
*/
constructor() {
this.first = null;
this.last = null;
}
only outputs the example on the class docs. I'm getting the same behavior with the patch.
As far as I can tell the only impact of the patch is to make a description not required.
Jsdoc2md has a convention: always write constructor docs (examples etc) in the documentation above the constructor statement, not the class. Try rewriting your docs like this: Does that solve your issue?
Well the original reason for this patch was to make a class like this output an example without having to put a description:
/**
* @class
* @example
* const list = new LinkedList();
*/
class LinkedList {
I guess my point is that when I first wrote something similar to the above class and it didn't output an example, I was kind of confused. My first thought wasn't "oh I need to add a description" -- I had to dig around in the code to figure out what was going on.
My main reason for creating this patch was so that other people don't run into this. I personally rarely use a description on a class since there's already @classdesc, and it wasn't obvious to me that a description had to be added for the example to work. That's totally fine if this behavior needs to stay this way. I could submit a note to the docs calling this behavior out?