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

SnapLogic is the leading self-service enterprise-grade integration platform. Download the 2018 GartnerMagic Quadrant for Enterprise iPaaS or play around on the platform, risk free, for 30 days.

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 ...

With SnapLogic’s integration platform you can save millions of dollars, increase integrator productivity by 5X, and reduce integration time to value by 90%. Sign up for our risk-free 30-day trial!

Topics:
documentation ,markdown ,web developer ,integration

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}