Recently private fields were coming in Firefox. They were already in Chrome browsers and Node,
so it's was time to migrate my code, replacing all closures in the code by real classes with
private and public fields. But when I have generated the documentation, I was disappointed
because the # was not recognized and a lot of things missing in the docs...
So I have quickly build ESSimpleDoc to have a correct documentation.
ES is there for EcmaScript. So it's not TypeScript, jsx or what you will...
Simple because my code structure is simple: only EcmaScript modules (not CommonJS modules!) and only classes declarations and variables declarations in the code
Because my old code was documented with JSDoc tags, I have keeped this, but only on a limited set of tags.
Each class, class property, class method or global variable that you document must have a leading comment block
starting with /** and finishing with */
All the text between the /** and the first @ char is considered as the description of the class,
method, property or variable.
These tags can also be used to give the description of the class, method, property or variable. All the text between the tag and the next @ char will be considered as a description.
This tag is used to document the type of a property or a variable. The tag must be followed by a type description between { }. All the text following the { } will be ignored.
These tags are used to document the return value of a method. The tag must be followed by a type description between { }. All the text following the { } is considered as a description of the return.
This tag is used to document a parameter of a method. The tag must be followed by a type description between { } and the parameter name, exactly as it is in the code. All the text following the parameter name is considered as a description of the parameter.
When this tag is present, the class, method property or variable will not be added to the documentation.
This tag is used to document a sample. All the text following the tag will be considered as a sample and added after the description in the documentation.
The types of the properties, variables, parameters and returns have to be documented between { }. Only JS script types, JS built-in objects and classes declared in your code are considered as valid types.
Arrays, Map and others containers can be follwed by a . folowed by the type of the contained objects between < > so the complete type of an array of strings is {Array.<String>}.
You can also add a ? before to type when the property, variable, type or param can be nullable.
You can use Markdown and html tags to document the classes, methods, properties, variables, returns and param descriptions.
See Github or Marked for more about Markdown.
Getters and setters are considered as properties and so you have:
- to document the getter
- to document the setter only when the getter is not present
- you have to add a @type tag
- you don't have to add a @param tag for the setters
- you don't have to add a @return tag to the getters
ESSimpleDoc uses @babel/parser to parse the code and then some tags are unnecessary.
Names are always extracted by the parser. But for params, you have always to add the param name in the @param tags, so ESSimpleDoc can do the link between the code and the documentation.
Private or public fields are detected by the parser, so the @private and @public tags are ignored.
Static methods and properties are detected by the parser so the @static tag is ignored.
Async methods are detected by the parser so the @async tag is ignored.
The super class is detected by the parser so the @extends tag is ignored.
ESSimpleDoc add a link to the class or variable documentation when the class or variable name is found in the description, so the @link tag is also ignored. And you can always use markdown to add a link in the documentation.
When ESSimpleDoc find a file named index.md in the src directory, this file is added to the home page.
When ESSimpleDoc runs with the --validate parameter, some verifications are done on the documentation and errors and warnings displayed.
Sorry... it's a limitation of ESSimpleDoc. You cannot have duplicate class names, or it's impossible to create a link to the class documentation...
No description found for a class, method, property or variable. Add a description
A type is unknown. Verify that the type is correct. If you are using external libraries, you can add types to the #mdnLinks property of the LinkBuilder class. Yes, I aggree, that will be better in a config file...
JS constructors cannot have a return. Remove the return in the code and the documentation
Getters are documented as properties. Add a @type tag.
Getters are documented as properties. Remove the @return tag
Same names are not used for the params in the code and the documentation or you have not the same number of params in the code and the documentation.
A @type tag is needed for a property. Add the tag.
A property cannot have a @param tag. Remove the tag.
A property cannot have a @return tag. Remove the tag.
A description is missing for a @return tag. Add a description
A type is missing for a @return tag. Add a type
Setters are documented as properties. Remove the @return tag
Setter cannot have a @type tag. Remove the @type tag
Getters and setters are documented as properties and only one documentation have to be done. Remove the documentation for the setter.
A setter don't have the corresponding getter and don't have documentation. Add a documentation for the setter.
The parameter must be followed by an = and the path where the source files are.
The path can be an absolute path or a relative path to the current working directory
The parameter must be followed by an = and the path where the documentation files will be placed.
The path can be an absolute path or a relative path to the current working directory.
If your source directory have subdirectories, the same directories structure will be created in the dest directory.
Warning. The dest directory will be completely erased when ESSimpleDoc start to avoid to have orphan files in the directory. Never place important files in that directory.
When present, the documentation is validated
When present, the HTML files are not generated
When present the home page of the documentation is directly opened in the browser.
By default, ESSimpleDoc show some JS keywords colored in the html version of source files added to the documentation. Also, links to the classes and variables are added in the html version of sources files added to the documentation.
When the --noSourcesColor parameter is present, JS keywords are not colored and links not added.
node ./PathToEsSimpleDoc/src/index.js --src=./PathToTheSourceFiles --dest=./PathToTheHtmlFiles --validate --launch
If you have installed ESSimpleDoc globally you can also do this:
esd --src=./PathToTheSourceFiles --dest=./PathToTheHtmlFiles --validate --launch
See the Grunt-ESSimpleDoc on Github or NPM.
By default, private methods and properties are hidden in the HTML classes files. You need to click on the ✔️# to show and on the ❌# to hide
Of course ESSimpleDoc is self documented. You can see the documentation on the github page of ESSimpleDoc
No really... it's impossible to create the links to the classes...
When a parameter of a method have a default value, you will always receive a 'Mismatch between the @param tags and parameters in the code' error.
Source files extension must be .js and not mjs
The best solution is to use npm directly from Node:
npm install essimpledoc --save-dev
But you can also download from Github.
ESSimpleDoc was build for my needs... So only the documentation for classes and variables declarations in ES modules is build.
You know surely JS as me. So if you find a bug or need a modification:
- You fork the repository
- You do the correction / modification
- If your modifications are usefull for others users, create a pull request
- eslint for the verification of the code
- @babel/parser for parsing the files
- Marked for parsing the markdown in the descriptions