RevDoc Brings HTML Docs
Use this handy tool to auto-generate documentation for your code

by Andre Garzia

Today I am introducing a new tool to the community. RevDoc is a tool to generate HTML documentation from inline comments inside your code. What happens today is that a lot of members from our community are sharing stacks and offering libraries, and while inspecting a 200 lines library to understand how it works is easy, trying the same thing with a complex library with thousand lines spread across different controls is a very difficult job.

We all know how most programmers hate to maintain documentation for their software and we also know how much developers love to have good documentation from their third-party tools, so RevDoc comes to help build a bridge between the boring act of writing documentation and the good feeling of having nice documentation to use. Instead of maintaining a separate document file, RevDoc will work with your stacks picking the "documentation comments" inside it. With that and data that it infers from your code, it will build HTML files for your documentation in a folder next to the stack.

It's easier demonstrated than explained. We know that a demo session is worth a thousand words, so, consider a library stack with the following code:

And these are the docs generated by RevDoc for that script:

You can also see it live here.

As you can see from the shot below, the first thing RevDoc does is look for a comment block at the very top of the script. This comment block is called "Read Me" and is put on a special place on the documentation. The comment block from the stack script is put on a separate file and it is the very first thing that appears in the documentation, so this is a good place for you to put your introduction and explanations. Below we show the block on the script editor and the generated readme:

and the Read Me:

Then it will pick comment blocks next to your method declarations, these will become the documentation for the given method. It will also inspect the declaration to check the scope (public or private) and nature of the method (command or function). There should be no spaces between the comment and the declaration. This is shown below:

In case you don't want a function or a full script included in the documentation, you simply add a "nodoc" to the comment above the method, or to ignore a full script you add it to the very first line of the script (thus ignoring all the functions and commands inside that script).

RevDoc will loop through all your stacks, cards and controls generating documentation for everything. The controls, stacks and cards will appear on the top middle section. Clicking them changes the top right section "methods", showing what is available on that control. In these screenshots, we have no other control or card scripts so they are not included.

RevDoc is a plugin stack, you just launch it and by clicking the generate docs, it will generate documentation for the topstack on a folder called "docs" placed just next to the stack file. RevDoc is a work in progress and I'll add features and improve the code over time. I built it out of necessity for documenting my own stacks. I was inspired by RDoc (from Ruby, yes, I borrowed their HTML template) and JavaDoc. There's still work to be done and I welcome any help. RevDoc is given free and unlocked to the community. Now you don't have any excuse not to document your stack! I hope you all enjoy and find this tool useful.

RevDoc is available here. A page will be put shortly at http://andregarzia.com

About the Author Andre Alves Garzia is 28 and lives in Brazil. He is usually coding something network related and created RevOnRockets. When not working, he enjoys SF Books, sailing and making pizza.