GSoC 2020: Documentation is equally important as code 📚

This article covers the automated documentation process for auto-generated code

Welcome back to another article about the Node Cloud project. In the previous article, I explained about Mocha configuration with Typescript and the unit tests which was written for the Transformers and Parsers in the code generation component. In this article, I will give an update on unit testing in the data extraction process and wrap up the unit testing discussion. Afterwards, I will describe the automated documentation process with JSDoc which is my main focus of this article.

Photo by NeONBRAND on Unsplash

As I told in the previous article, I was doing some code changes to isolate the data extraction process of the cloud SDKs for unit testing. After that, I had to prepare dummy data to test the data extraction unit. This unit requires a parsed type definition file(.d.ts file) and an object which contains data related to SDK functions. Dummy data is stored in a sperate directory as JSON files and text files. Because of an issue in TS-Node the type definition files couldn't be stored in the exact same format. Instead, it was stored as text files. Since the source code is required in string format there is no harm of saving it as a text file. I have written unit tests for the data extraction process covering several contexts in each cloud provider. You can have a look at them in the #59 PR. I demonstrated the written unit tests for my mentors in the weekly sync-up call on Saturday. This brings writing unit testing to an end :)

Now let’s hop into the main topic of this article which is documentation. Documentation helps to understand code better. There are two main parts that I need to cover here,

1. Updating the “README” files: This covers the setup instructions for Node Cloud, Code generator architecture and other necessary information for developers
2. API documentation for Node Cloud plugin classes: This is autogenerated with the help of JSDoc

I looked into available documentation libraries for NodeJS and found JSDoc. JSDoc is a well-recognized package for documentation. Once we set comments in a format required by JSDoc it automatically creates a static web site that contains all the necessary information about Node Cloud API which is something really cool! Here is an example created for Node Cloud AWS plugin with what I have achieved up to now.

This is something still under construction, some required data is missing here

The TypeScript compiler is capable of identifying JSDocs, which makes easier to auto-generate JSDocs when transforming source code. I am currently in the process of updating the transformers to fill up the JSDoc Node with necessary data. Along with that, I am also updating the “README” files with the necessary updates. Below image shows the JSDoc node in the Abstract Syntax Tree.

JSDoc Node in the Abstract Syntax Tree

Mocha unit tests for generators by rajitha1998 · Pull Request #59 · leopardslab/nodecloud

That’s pretty much it for this article. Keep in touch to read more updates about the Node Cloud project.

Cheers 🍻 !!