Hire the author: Abhinav R
Documenting react components manually is time-consuming and difficult to maintain, which often leads to poorly documented projects. ESDoc is a documentation generator for Javascript and can be used readily with our React setup. It relies heavily on documentation tags (@something) to generate a summary of the written code. This summary includes:
- Collections
- Components
- Services
- Pretty much any code snippet with javascript docs – class, function and file descriptions.
This library is extremely easy to use, but it relies on our documentation capabilities as the more exhaustive our documentation for each function, class or file is, the more versatile ESDoc can generate the summaries.
ESDoc doesn’t just generate the documentation summary. It creates a single-point of entry to view and understand the entire repository, including code.
Glossary
- ESDocs – ESDoc is a good documentation generator for JavaScript official docs here.
- ReactJS – React is a JavaScript library for building user interfaces
- Components – Components let you split the UI into independent, reusable pieces, and think about each piece in isolation.
How to use ESDoc
Follow the instructions at https://esdoc.org/ to get esdoc installed on your repo. Or, use these commands:
// Installing the library.
$ npm install --save-dev esdoc esdoc-standard-plugin
// Creating the esdoc.json file with config.
$ echo '{
"source": "./src",
"destination": "./docs",
"plugins": [{"name": "esdoc-standard-plugin"}]
}' > .esdoc.json
// Run esdoc to generate documentation
$ ./node_modules/.bin/esdocThis would generate a summary report at <your-repository>/docs.
- We can open the index.html file, which is in docs to view the complete report.
- Easily navigate through the entire repo which allows you to view all the documentation in one place.
- All the tags supported by ESDoc can be found at https://esdoc.org/manual/tags.html. We need to make our documentation as robust and complete as possible.
Learning Tools
- ESDocs ( docs )
- blog.learningdollars.com
Other features:
GUI-way to view code:
- View the /docs/source.html
- This will provide a nice table of contents to view all source code within your repo. As a result, it becomes easier to traverse through.
- A quick tip is to add a link to this ‘/docs/source.html’ in your repo’s readme file, therefore, providing instant access to anyone viewing the repo.
View the actual source code in a structured way
- Developer’s, Business Analyst’s and any curious minds can simply click view the ESDocs instead of cloning the repo locally and going through each file.
- Visiting /docs/file will provide a GUI-based structure that allows you to view all the source files.
View all functions in one place
- Devs willing to check if a particular function exists can visit /docs/function/index.html to display all the functions in one place which is helpful and saves time.
- Function names are provided with an introduction as well.
View all variables in one place
- Visiting /docs/variable/index.html lists all variables used across the repo
Coverage
- Visiting /docs/source.html mentions the documentation coverage.
- We can set targets around this like we do for test coverage.
Reflective Analysis:
- Industry expectations
- We are expected to have high standards of documentation in addition to code and testing standards.
- Code documentation coverage can be tested in individual tasks and the ESDoc report checked during review.
- Easy for new devs to learn
- Devs need not go through the code or ask around when tasked to work with a new repo.
- They can check the ESDoc report to understand not just the overall repo but the nitty-gritty details as well.
- Non technical people can also understand what’s going on.
- Business Analysts, Team Leads and personnel across teams can use ESDoc and at least understand what the repo or function does.
- Completely non-technical folks may not be benefited a lot since the documentation is generated from technical stuff.
- Easy for testers to map their test plans.
- Quality Analysts, like devs, need not have to traverse through all the files to chart out a test plan.
- The coverage report gives an exhaustive account of the entire structure consequently.
- Handling complexity
- For instance, Complex repos will grow and get more difficult to manage as time progresses.
- ESDocs can be our friend for the reason that it makes it easy to understand and manage large repos.
- Eliminates confusion
- This would stop people from building the same functionality multiple times. It can even eliminate confusion when it comes to coding practices, as a view of the documentation would sort things out.
- One-stop entry point
- Everyone looking at a repository can use this as the entry point, hence single-point entry to avoid confusion.
Conclusions:
If while developing new components dev’s develops a habit to put in proper comments as per ESdocs recommended standards, there is hardly any need to create documentation around new components and ESdocs can generate an exhaustive documentation for you and team to refer from. Also, comments would stay in code as it uses to be. Esdoc just provides an interactive way to access documentation.
If you found this article helpful kindly share it to help others as well. You can find more exciting learning materials here. Cheers!
Citation: Featured image used in this blog is taken from Jory MacKay’s blog on plan.io.
Abhinav Rana very nice work, the article is very helpful both for Expert Developers and new Developers. At times we developers create Complex code and get more difficult to manage as time progresses, ESDocs can be our friend for the reason that it makes it easy to understand and manage large repos. It’s also helpful for project presentation as it gives the general code overview of the project in a simple understandable way even for non-technical people to understand. It’s also nice to note that sometimes we distribute our documentation as a zip package. Instead of using a custom npm script, we can use a plugin to let ESDoc handle the zipping after generating all the documentation.