‘doc-coverage’ — A Documentation Coverage Tool for Javascript

Witten by Shivani Sehgal

It’s been rightly said that what gets measured gets managed! A few months ago, we at ShareChat decided to go on a documentation coverage spree. Not long into the journey we realised the resources for measuring documentation were limited and would not meet our expectations. That’s when we decided to step up and fill this gap with an open source package — ‘doc-coverage’.

First things first — we began by defining what documentation means to us.

A JS repository is considered 100% documented when —

• All the top level functions in JS files have a leading documentation comment. As of now we do not check the content of the comment. As long as it is there, we consider the function to be documented. We recommend and use the JSDoc documentation syntax. However, your comment does not need to be exactly like that to be identified by the script. It only needs to be a multiline comment starting with ‘/**’.

/**
* @param {very_long_type} name Description.
* @param {type} very_long_name description.
* @returns {type} very_long_name Description.
*/

• All the non JS files (JSX/Vue/Svelte Files) either have a story or have all Prop Types defined.

For JSX/React — Both static Prop Types (in case of class based components) and Prop Types defined on an instance of the component(class based or functional) are supported.
For Vue — Props need to be defined as an object and not as an array
For Svelte — A library called prop-types can be used. Refer this link for an example.

How is the Documentation Coverage calculated?

For pure JS files, the score is simply the percentage of documented top level scopes/functions by the total top level scopes.

For Component Files, three types of scores are calculated -

1. Fully-documented Components — Percentage of components with either a story or all prop types defined by total components.
2. Storybook Coverage — Percentage of components with stories by total components.
3. Prop Types Coverage — Percentage of the Total Number of Prop Types by Total Number of Props

And Finally, three Overall Scores of the project are calculated by combining the pure JS File Coverage with each of the Component File Coverage Score.

Sample Result

Tabular summary of the result in the console

Detailed Results can be found in the file called docCoverageReport.json in the root of the project. It provides file-wise coverage as well.

For JS files, we get the names of all the top level functions detected by the script followed by a boolean which depicts whether it is documented or not.

For Component Files, we get details like whether the component has a story or has prop types. In cases where prop types are present partially, we also get the list of missing prop types.

1. fileWiseCoverageJSDoc - Object with file path as the key.
    Example:
    "path-to-app/src/app.js": {
            "funcCoverage": {
                "urlB64ToUint8Array": false,
                "onMessageReceivedSubscriptionState": true,
                "onMessageReceivedSubscribe": true,
                "onMessageReceivedUnsubscribe": true,
                "broadcastReply": true,
                "persistSubscriptionLocally": true
            },
            "fileCoverage": "83.33%"
        },

 2. fileWiseCoverageComponent - Object with file path as the key.
    Example:
    "path-to-app/src/index.js": {
            "hasStory": false,
            "hasAllPropTypes": false,
            "componentType": "Functional",
            "missingPropTypes": [
                "error",
                "timedOut",
                "pastDelay"
            ],
            "coverage": "25%"
    }

Quick Start

Install via NPM :
npm i doc-coverage

Go through the Readme for details on how to use and configure the package according to your project.

Conclusion

‘doc-coverage’ is a one of a kind documentation coverage tool for Javascript based projects. It considers Documentation Comments, Stories and Prop Types for calculating the score. As of now it supports 3 frameworks — React, Vue and Svelte. It requires node version 14 or above.

We intend to actively maintain this package and welcome any suggestions or bug reports.

Cover illustration by Ritesh Waingankar