Modern requirements to autodocumenting source codes

It has long been a well-known expression that programs are written not for computers, but for humans since there is binary code for computers. Convenience and readability of the program code of your system is the key to the success of your project in the future. One of the important factors in maintaining the program code is documentation. 

The quality of the documentation will help you continue to develop new features and maintain the system in operation for decades.  Auto-documentation systems are best suited to describe the code and help developers keep the project in a consistent state. Let's look at the approaches to the development of auto-documentation and the main examples of auto-documentation systems.

What is Source Code Documentation

The documentation for software in modern conditions is interactive (online) documentation and reference text or printed user manual, describing how to use the software product.

There are four main types of software documentation:

• architectural / design is a software review that includes a description of the work environment and the principles that should be used when creating software
• technical documentation on code, algorithms, interfaces, API
• user guides for end-users, system administrators and other staff
• marketing

A program document is a document containing, depending on the purpose, the data necessary for the development, production, operation, maintenance of a program or software.

The documentation for the program is of two types. The first is in the program code itself in the form of comments. The second option is to use a third-party tool or a separate storage place, for example, a WIKI website, which describes the concepts of the application, examples of use, the interaction between modules, provides different flowcharts and diagrams, and, in general, everything that cannot be placed in code. Here is a typical structure of an autodocumenting system, for example, Doxygen.

Image source

Why documenting source code

When a young developer and a senior developer start discussing code documentation, the young one often asks these questions:

• Why do you need comments on the program code?
• In what form are they written?
• Where are they needed and where not?
• How to comment code correctly?
• How to adhere to the same style of documentation for all team members?
• What are the tools for generating documentation?

When creating a program, code alone is usually not enough. Some text should be provided that describes various aspects of what the code does. Such documentation is often included directly in the source code or provided with it.

Such documentation is highly technical in nature and is mainly used to define and describe APIs, data structures, and algorithms.

Often, when compiling technical documentation, automated tools are used - documentation generators such as Doxygen, Javadoc, NDoc, and others. They receive information from specially designed comments in the source code, and create reference manuals in some format, for example, in the form of text or HTML.

The use of documentation generators and documentary comments by many programmers is recognized as a convenient tool, for various reasons. In particular, with this approach, the documentation is part of the source code, and the same tools can be used to build the program and simultaneously assemble the documentation for it. It also simplifies keeping the documentation up to date.

Who needs this documentation and who are the most valuable users: software developers, project managers, software architects, usability engineers, interaction designers, and testers.

Autodocumenting Systems

Now back to the documentation of the code in the code itself. The first message Robert Martin tries to convey to us in the book “Clean Code” is that comments are a sign of failure. Comments are written in order to make amends for a programmer who could not clearly express his thoughts with the help of a programming language. 

There are many references for writing good and understandable code and the process is beyond the scope of this article. But still, the simplest rule of good code is: write it in such a way that it reads like normal sentences. In object-oriented programming, everything is much simpler than in functional; the generally accepted practice of calling classes nouns, and methods as verbs, makes the code more natural.

Doxygen

One of the most universal and respected code auto-documenters is Doxygen (which can generate documentation for all, well, almost all, programming languages: C ++, C, Objective-C, Python, Java, IDL, PHP, C #, Fortran, VHDL).

Documentation comments apply to:

• class documentation
• interfaces
• fields (variables)
• designers
• methods
• packages

In each case, the comment must appear before the document element.

The following descriptors can be used to document the variable: @see, @serial, @serialField, {@value}, @deprecated. For classes and interfaces, you can use descriptors: @see, @author, @deprecated, @param, @version. Methods can be documented using descriptors: @see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @excertion.

Descriptors {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} can be used anywhere.

Classes can also be documented simply by preceding them with a documenting block. At the same time, Doxygen receives a huge amount of information automatically, given the syntax of the language, so the task of documenting classes is greatly simplified. So when documenting, Doxygen automatically defines methods and members of the class, access levels to functions, friendly functions, etc.

It is very important that Doxygen allows you to use TeX formulas directly in the documentation; it is very convenient and the result is very decent. However, it is worth noting that there are limitations: at the moment, formulas can only be inserted into the HTML and LaTeX documentation, but this is usually enough.

Here is an example of Doxygen documentation with images and class descriptions. 

Javadoc

Javadoc (for Java only)

Javadoc is an HTML-based documentation generator for Sun Microsystems Java source code comments. This format was chosen to allow the linking of linked documents. Javadoc comments have become the "de facto" standard for documenting Java classes created. Most development environments like Eclipse and Netbeans automatically generate documentation using Javadoc.

Javadoc also provides an interface for creating doclets and tokens that allow you to analyze the structure of a Java application. The comments provide an opportunity to add information about it that can later be used by the Javadoc utility (included in the Java Development Kit) to create HTML files. Documentation comments can be used when commenting:

• fields (variables)
• methods
• designers
• classes
• interfaces
• packages

Also,  the comments can use standard HTML tags, such as <strong>. However, the use of some of them is prohibited, such as headers violating the appearance of the HTML file generated by the Javadoc utility.

Please refer to the following link to get more information about Javadoc.

JSDoc

jsdoc (Javascript)

JSDoc is a documentation generator in HTML format from JavaScript source code comments. The earliest example of using Javadoc-style comments to document JavaScript code came in 1999 and the Netscape / Mozilla Rhino project. 

As mentioned in JSDoc documentation “JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you. Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your source files.”

The JSDoc syntax is similar to the Javadoc syntax, which is used to document Java code. But JSDoc is designed to work with the JavaScript language, which is more dynamic, and therefore JSDoc is not compatible with Javadoc. Like Javadoc, JSDoc allows the programmer to create doclets and tags that can be output to a file, such as HTML or RTF.

The following list of tags are supported:

• @author Developer Name
• @constructor Marks a function as a constructor
• @deprecated Marks the method obsolete and not recommended
• @exception Synonym for @throws
• @param Describes a function argument; you can specify the type by specifying it in braces
• @private means that the method is private
• @return Describes the return value
• @returns Synonym for return
• @see Describes a relationship with another object
• @this Specifies the type of the object pointed to by this keyword inside the function.
• @throws Describes the exceptions thrown by the method
• @version library version

Here is an example of JSDoc documentation. 

Image source

phpDocumentor

The phpDocumentor is a PHP source documentation system. It has built-in support for generating documentation in HTML, LaTeX, man, RTF and XML formats. Also, the output can be easily converted to CHM, PostScript, PDF.

It can be used both from the command line and using the Web interface. It understands the syntax of the 4th and 5th versions of the PHP language and is distributed under the LGPL license.

The system is based on parsing the logical structure of PHP code (classes, functions, variables, constants) and binding comments written to it according to certain standards. Here is a list of the standard tags:

• @access
• @author
• @copyright
• @deprecated
• @example
• @ignore
• @internal
• @link
• @see
• @since
• @tutorial
• @version

Unlike regular tags, Inline tags display in the text flow where they appear:
 

• inline {@example}
• inline {@id}
• inline {@internal}}
• inline {@inheritdoc}
• inline {@link}
• inline {@source}
• inline {@toc}
• inline {@tutorial}

Also, PHPDocumentor can use different templates, for instance:

Image source

GhostDoc

GhostDoc (C#, Visual Basic, C++, JavaScript). As mentioned in GhostDoc documentation it is “a Visual Studio extension for developers who need to Generate XML Comments from source code using customizable templates, maintain clean and up-to-date documentation, produce help documentation in multiple formats, use intelligent source code Spell Checker in Visual Studio, and more.

GhostDoc also helps to automate the generation of clean, helpful documentation of your clean code, building it, and packaging it up all without human intervention.”

The advantages of GhostDoc are  the following:

• Automatically generate a starting point for your help documentation
• The benefit of the base class documentation
• Visual Editor for XML Comments
• Produce help documentation in multiple formats
• Maintain clean and up-to-date code documentation
• Generate help documentation from your build
• Contemporary help documentation themes
• Intelligent source code Spell Checker
• StyleCop compliant documentation templates

GhostDoc supports Visual Studio 2019 and the previous version. This is one of the best VisualStudio extensions for documenting code and it is highly recommended for developers. Also, there is a GhostDoc Pro version for advanced users.

Docurium and RDoc

Docurium or YARD (Ruby). As mentioned on GitHub “Docurium is a lightweight Doxygen replacement. It generates static HTML from the header files of a C project. It is meant to be simple, easy to navigate and git-tag aware. It is only meant to document your public interface, so it only knows about your header files. Though Docurium can generate your docs into a subdirectory, it is meant to be served from a web server, not locally. It uses XMLHttpRequest calls, which cannot be done locally, so you can't just open the index.html file locally and have it work - you need to either run a web server in the output directory or push it to a website to view it properly. I use Pow (pow.cx) or GitHub Pages.”

RDoc is another tool developed by Dave Thomas. This is the built-in documentation generator for the Ruby programming language. If you also want to do source code analysis, then RDoc is great for this. It generates a structured collection of pages for Ruby. Objects and methods and even code comments can be added in a natural style. RDoc is now included as part of the Ruby kernel distribution.

RDoc can create effective documentation, even if the target source code contains few explicit comments. This is possible because RDoc will still analyze classes, modules, and methods and list them in the generated files. RDoc also provides a mechanism for creating Ruby ri data files and providing access to API information using the command line.

As the conclusion of this article, we want to say: document your code. Some clients will ask you to return to a project that you did, for example, 10 years ago. You will need to remember what you did in this code and quickly figure out what is happening in it. It will not be easy, as time passes and the important nuances of implementation are forgotten. Believe me, you will be very grateful to yourself for writing good auto-documentation. Do not spare time for compiling the documentation and commenting on the code, but do not get carried away excessively with this process, everything should be moderate.

Our specialists from Svitla Systems will create your project according to the requirements and provide the necessary amount of documentation and testing of the system. Our experts will document your existing code according to the highest standard. Svitla Systems company wishes you effective and successful projects.