Closed marcnicole closed 1 year ago
Hello Marc. Thanks for using this package. I wrote this code more than 4 years ago so I might be wrong but I think that the list of doclets comes from JsDoc and I'm only playing with this list to reorder and decorate them, then applying a handlebar template. I'm still using this plugin for aurelia projects where class constructors are important (because of IOC) and constructor documentation is fine. I'm glad that you find a work around in the meantime. As far as I remember the way JsDoc convert real code to doclet is not very intuitive. I guess the Javascript language and the various ways of importing modules do not help. Anyway I will take a look at your sample in the next days.
In fact this plugin has been written and tested for two common scenarios:
Can you try to remove the @module jsdoc? All comments and @category of the @module section can be defined at the class level. Let me know if this fixes your issue. If so I will update the documentation.
Thanks, I'll check it out tomorrow and let you know
Le jeu. 14 juil. 2022, 10:05, KisssDev @.***> a écrit :
In fact this plugin has been written and tested for two common scenarios:
- a javascript file that does not include class, then a @module https://github.com/module jsdoc comment is required
- a javascript file that includes a single class, then the @module https://github.com/module must not be included it will be automatically inferred. If you include it then it will defeat the logic that creates the documentation tree. Can you try to remove the @module https://github.com/module jsdoc? All comments and @category https://github.com/category of the @module https://github.com/module section can be defined at the class level. Let me know if this fixes your issue. If so I will updated the documentation.
— Reply to this email directly, view it on GitHub https://github.com/kisssdev/kis-jsdoc-plugin/issues/14#issuecomment-1184129868, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABPFHIBPFP73RG5XS3CUQYLVT7C3FANCNFSM53O5XRKQ . You are receiving this because you authored the thread.Message ID: @.***>
I tried to remove the module comment, but it still doesn't work
/**
* construit un objet Drill
* @category formes
* @param {object} options - les option du drill
*/
export class Drill {
constructor(options) {
this.options = options;
}
/**
* just a dummy method
* @param {object} options - les options de maMethode
*@public
*/
maMethode(options) {
}
}
I still don't see the constructor
I tried to put the comment at the constructor level
export class Drill {
/**
* construit un objet Drill
* @category formes
* @param {object} options - les option du drill
*/
constructor(options) {
this.options = options;
}
/**
* just a dummy method
* @param {object} options - les options de maMethode
*@public
*/
maMethode(options) {
}
}
in that case it produces almost nothing (which is normal since probably the class is considered as not documented)
You need to comment the class and the constructor (as a regular method)
/**
* implémente la classe Drill
* @category formes
*/
export class Drill {
/**
* construit un objet Drill
* @param {object} options - les option du drill
*/
constructor(options) {
this.options = options;
}
/**
* just a dummy method
* @param {object} options - les options de maMethode
*@public
*/
maMethode(options) {
}
}
In fact, looking at your code I just don't undestand when should we get a "constructor" that would end in the "constructors" that are used in class.hbs.
I just modified index.js
const processDoclet = (doclet) => {
if (doclet.name === 'Drill'){
console.log('processDoclet ',doclet)
}
return Object.keys(processConfig)
.filter((k) => processConfig[k].condition === undefined || processConfig[k].condition(doclet))
.forEach((k) => (processConfig[k].process || defaultProcess(processConfig[k], k))(doclet));
}
my source drill.js
is
/**
* construit un objet Drill
* @category formes
* @param {object} options - les option du drill
*/
export class Drill {
/**
* mon constructeur
* @param {*} options
*/
constructor(options) {
this.options = options;
}
/**
* just a dummy method
* @param {object} options - les options de maMethode
*@public
*/
maMethode(options) {
}
}
and got as output
processDoclet Doclet {
comment: '/**\n' +
' * construit un objet Drill\n' +
' * @category formes\n' +
' * @param {object} options - les option du drill\n' +
' */',
meta: {
range: [ 105, 377 ],
filename: 'drill.js',
lineno: 6,
columnno: 0,
path: 'C:\\Users\\mnicole\\Documents\\dev_Novacel\\@novacel\\forms\\lib',
code: {
id: 'astnode100001993',
name: 'exports.Drill',
type: 'ClassDeclaration'
}
},
classdesc: 'construit un objet Drill',
category: 'formes',
params: [
{
type: [Object],
description: 'les option du drill',
name: 'options'
}
],
name: 'Drill',
longname: 'Drill',
kind: 'class',
scope: 'global'
}
processDoclet Doclet {
comment: '',
meta: {
range: [ 112, 377 ],
filename: 'drill.js',
lineno: 6,
columnno: 7,
path: 'C:\\Users\\mnicole\\Documents\\dev_Novacel\\@novacel\\forms\\lib',
code: {
id: 'astnode100001994',
name: 'Drill',
type: 'ClassDeclaration',
paramnames: [Array]
}
},
undocumented: true,
name: 'Drill',
longname: 'Drill',
kind: 'class',
scope: 'global'
}
processDoclet Doclet {
comment: '/**\n * mon constructeur\n * @param {*} options \n */',
meta: {
range: [ 187, 241 ],
filename: 'drill.js',
lineno: 11,
columnno: 2,
path: 'C:\\Users\\mnicole\\Documents\\dev_Novacel\\@novacel\\forms\\lib',
code: {
id: 'astnode100001997',
name: 'exports.Drill',
type: 'MethodDefinition',
paramnames: [Array]
}
},
description: 'mon constructeur',
params: [ { type: [Object], name: 'options' } ],
name: 'Drill',
longname: 'Drill#Drill',
kind: 'class',
memberof: 'Drill',
scope: 'instance'
}
I never dealed explicitly with constructors. There is the processDoclet in index.js that enrichs the doclet objects and the buildTree in publish.js that builds the documentation hierarchy relying on the longname property. The class.hbs handlebar template references the constructors handlebar partial template which in turn loops on the classes property of the doclet.
Regarding class files, I'm using this plugin with aurelia and there is always an 'inject' decorator on every classes. By removing the inject decorator I have the same behavior as your sample: constructor is not present. I will try to fix this in a futher release.
Ok, I now undestands why it doen't work for me.
In the mean time I will use the workaround I described above.
Thanks for your help
Thanks for your quick answer.
I must admit i was a bit lost debugging jsdoc code.
Thanks for your help
Marc
Le mer. 13 juil. 2022, 18:25, KisssDev @.***> a écrit :
Hello Marc. Thanks for using this package. I wrote this code more than 4 years ago so I might be wrong but I think that the list of doclets comes from JsDoc and I'm only playing with this list to reorder and decorate them, then applying a handlebar template. I'm still using this plugin for aurelia projects where class constructors are important (because of IOC) and constructor documentation is fine. I'm glad that you find a work around in the meantime. As far as I remember the way JsDoc convert real code to doclet is not very intuitive. I guess the Javascript language and the various ways of importing modules do not help. Anyway I will take a look at your sample in the next days.
— Reply to this email directly, view it on GitHub https://github.com/kisssdev/kis-jsdoc-plugin/issues/14#issuecomment-1183429619, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABPFHIE5B3AHS5DO6MVFDCLVT3UWXANCNFSM53O5XRKQ . You are receiving this because you authored the thread.Message ID: @.***>
The bug was due to a change in the jsdoc behavior. Now jsdoc marks some doclet as 'undocumented' and as all undocumented doclets were removed during publishing, constructors entries were also removed.
Describe the bug
doesn't document the constructor
To Reproduce just install like in the doc run jsdoc
the md is
Expected behavior should look like
Additional context after trying to debug, found that no doclet is considered as "constructors" ==> the constructor.hbs template produces nothing
in order to patch the problem, I modified the class.hbs