Enhance documentation high quality for LWC
No developer actually likes writing in depth code documentation, particularly if it’s a separate doc far-off from the precise code. Nonetheless, having well-written documentation is in fact crucial.
Let’s take for instance the LWC library that gives reusable or pattern elements for others. It’s essential that everybody who ought to profit from this understands how a selected element works and learn how to use it.
Happily, with JSDoc there’s a simple approach to routinely generate a clear doc in varied codecs from moderately written feedback in our code.
By correctly annotating and tagging our lessons and public properties with applicable tags, we make it attainable to later routinely generate a well-formatted, cohesive doc from our elements.
To attain the documentation proven above for our Good day World pattern element, its code have to be annotated as follows:
For extra data concerning the proper use of JSDoc feedback, annotations, and tags, please check with the official documentation here.
To begin with, we have to set up the most recent JSDoc model through npm. We will do that both globally or domestically as a dev dependency of our present SFDX venture. Let’s simply set up it domestically and reserve it in our venture’s
bundle.json file by working:
npm set up --save-dev jsdoc
In case you nonetheless need to have it put in globally, then merely run the next:
npm set up -g jsdoc
After the set up we nonetheless must create the suitable configuration for JSDoc. For this we create a brand new
jsdoc.config.json file within the root listing of our SFDX venture with the next content material:
We additionally set a brand new listing
/docs because the output listing for our generated documentation. By including the “readme” possibility on the finish, we’ve moreover outlined that the
README.md within the root listing of our venture ought to be used as the primary web page of our generated doc.
All in all, it is a pattern configuration and could be personalized as desired with many different choices accessible.
After annotating all our elements with correct JSDoc feedback and finishing the JSDoc setup, we will lastly generate our documentation information. For ease of use, we add the next command to the “scripts” part of our
Lastly, we will generate the doc with the next command:
npm run docs:lwc
The generated code documentation can now be discovered within the newly generated
/docs listing in our venture.
As well as, the documentation technology script we created may be run in an automatic pipeline, e.g. after code modifications have been launched, to create the up to date doc after which routinely publish it someplace.
If in case you have any additional questions concerning the subject normally or wish to make recommendations for enchancment, be at liberty to go away a remark beneath.