Article Preview
Buy Now
REVIEW
RB-ADoc 1.1.1
Issue: 3.3 (January/February 2005)
Author: Greg Fiumara
Article Description: No description available.
Article Length (in bytes): 4,059
Starting Page Number: 10
Article Number: 3306
Related Web Link(s):
http://www.parkbenchsoftware.com/
Full text of article...
Every developer knows all too well that the documentation of a product is often the hardest part of the production cycle. Documentation can be harder than marketing, programming, and debugging combined. Often, you need to come back to your code weeks or even months after you wrote it in order to add a feature or fix a bug. When you launch your project, all of your properties and methods no longer have any meaning to you if you did not document your code. Now, thanks to RB-ADoc from Park Bench Software, you can note information about many components of your project, expanding greatly upon source code comments.
After using RB-ADoc for a short while, one becomes accustomed to its usage and feel. This is one of those programs that, if you do not read the documentation, you will become lost and quickly confused. The power of RB-ADoc rests in what you, the programmer, add to REALbasic. The program parses a saved XML version of a REALbasic project file and searches for "special markers." The programmer needs to add the special marker into their code and RB-ADoc will interpret the comments trailing it. Like all great programs, there is more than one way to accomplish this goal. Using a special syntax within a REALbasic note will allow the programmer to comment properties, constants, and the like with RB-ADoc.
RB-ADoc displays the comments you provide in an HTML document rather than within the program itself. Because it uses REALbasic to add comments, they will always be visible when you work on a project. The HTML pages it creates are completely customizable and its template structure is worthy of praise in and of itself. Using a string of special HTML comments, the way in which RB-ADoc exports your comments into HTML is completely up to you. A recommendation to open-source developers would be to create a template similar to your project's web site and then upload RB-ADoc's exported file to your web site.
As with most good things, there are also bad -- RB-ADoc being no exception. The interface to the program seems very clunky and disorganized. Unless there are certain parts of your project you do not want exported into the HTML page or you are editing the HTML template, you really only need the program's "export" button. The tragic flaw to this program is in its implementation. If you have created a program with hundreds of classes and properties, in order to use RB-ADoc you will have to learn the new syntax for commenting and re-examine the contents of your code. For a developer just starting on a large project, RB-ADoc can be an angel, but if you have discovered its power too late, RB-ADoc may well be a pain to use.
The commenting power of RB-ADoc, regardless of some negative traits, can be a diamond in the rough to several organized programmers.
End of article.