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

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

 * Creates a modal widget, with a MySQL datagrid inside of it.
        innerValue:Hypereval snippets

       * Our actual datagrid.

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

documentation ,integration ,markdown ,web developer

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}