-
Notifications
You must be signed in to change notification settings - Fork 19
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix: es6 constructor docs generation (fixes #33) #34
base: master
Are you sure you want to change the base?
Conversation
I now remember why the /**
* @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 ExampleKind: global class new Example()Example const linkedList = new LinkedList() new Example()Example const whatAbout = 'this' example.oneAn instance variable Kind: instance property of ExampleKind: global class new Example()Example const linkedList = new LinkedList() new Example()Example const whatAbout = 'this' example.oneAn instance variable Kind: instance property of |
Jsdoc2md has a convention: always write constructor docs (examples etc) in the documentation above the /**
* @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 () { }
} |
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 As far as I can tell the only impact of the patch is to make a description not required.
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 |
This fixes addresses the linked issue:
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 forexample
tags as well.