Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Creating Documentation for Your Software in Zero Seconds

DZone's Guide to

Creating Documentation for Your Software in Zero Seconds

Read this tutorial in order to learn more about how to quickly create documentation for your software and also includes pictures for reference.

· Integration Zone ·
Free Resource

The new Gartner Critical Capabilities report explains how APIs and microservices enable digital leaders to deliver better B2B, open banking and mobile projects.

For as long as we have created software, we have tried to invent intelligent constructs for having our documentation automatically generated. Trolltech was one of the pioneers of this approach and later came tools such as Doxygen and the XML documentation in Visual Studio. The reasons are obvious: to make sure the software and its documentation are always "in sync.The Phosphorus Five solution is arguably the most dynamic of these approaches. See a screenshot of it below.

Image title

First of all, it doesn't need any compilation or building process to occur to generate your documentation. In fact, as you choose to view the "meta information" for your documentation, the help system will automatically generate its documentation on the fly, not even caring to cache it. This has several advantages, one being that the documentation for your system is always "in sync" with your source code. If you delete a source code file or edit it, the documentation automatically updates itself accordingly. Below is a video demonstrating this.


The above is of course mostly for "reference documentation," documenting your files, "functions," "UserControls," etc. If you want to create more of a "tutorial style" type of documentation, you'll probably not want to include these parts directly into your source code or comments — since this will make your source code files comments ridiculously long. For "tutorial style documentation", you can use Markdown. This allows you to easily format your documentation. Below is an example of such a documentation file.

## Extension widgets - MySQL Datagrid

This widget allows you to create a _"datagrid"_ that automatically
databinds towards a MySQL database table. Below is an example that
assumes you have Hypereval installed in your Phosphorus Five
installation.

```hyperlambda-snippet
/*
 * Creates a modal widget, with a MySQL datagrid inside of it.
 */
create-widgets
  micro.widgets.modal
    widgets
      h3
        innerValue:Hypereval snippets

      /*
       * Our actual datagrid.
       */
      micro.widgets.mysql.datagrid
        database:hypereval
        table:snippets
        columns
          name
```

The __[micro.widgets.mysql.datagrid]__ extension widget expects the
following arguments.

- __[database]__ - Which database to databind your datagrid towards.
- __[table]__ - Which table to databind your datagrid towards.
- __[columns]__ - Collection of which columns for your datagrid.

... etc ...

Notice the funny "language declaration" parts above. This parses the code as Hyperlambda and automatically injects an "Evaluate Hyperlambda" button in your resulting documentation — allowing the reader of the documentation to immediately "execute" the snippet to see its result. This makes your documentation become "living," allowing the user to directly execute code snippets without even having to copy and paste them into his IDE. See a screenshot of how this will look like when "executed."

Image title

Maybe the header for this article was slightly exaggerated, but if you've read this far, I believe you can hopefully forgive me for that small exaggeration — realising the benefits of the above documentation system. Also, notice how the meta documentation system will automatically extract meta information such as.

  • Module's installation date
  • Module's size in KB, also relative to all other modules, with charts, arguably illustrating its relative complexity
  • An exact number of comments in the module as a whole
  • Code to comments ratio, also with a pie chart
  • An exact number of lines of code in the module
  • Etc, etc, etc

All of the above is automatically generated without you having to even lift your fingers and type a single character on your keyboard. Not too bad I'd say for "zero" seconds of work.

You can download Phosphorus Five here ...

The new Gartner Critical Capabilities for Full Lifecycle API Management report shows how CA Technologies helps digital leaders with their B2B, open banking, and mobile initiatives. Get your copy from CA Technologies.

Topics:
documentation ,markdown ,web developer ,integration

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}