Everybody knows it. Documentation is essential. Most people hate two things about it. The first one is to create it, the second to read it.
The Java community has JavaDoc. This takes care of both objections. Generate the documentation so you don’t have to write it. You still have to read it, there’s no shortcut here however JavaDoc is fairly straightforward to use, easy to navigate to the area of interest and this helps you locate that piece of documentation you need.
That’s all nice for the Java community, what about us Oracle Forms Developers? There’s FoReDoclet.
FoReDoclet can generate HTML documentation for Oracle Forms. It includes the form, menu, PL/SQL library and object library.
Comments you write while creating your Form will be included in the generated documentation. For Program Units you can include comments not only in the Comments-property, but also in PL/SQL Editor.
Whether you use single-line comment (
--), or multi-line comments (
/*...*/) it doesn’t matter, FoReDoclet takes care of it. To make things even more flashy, you can even use HTML in your comments.
What about the “regular” JavaDoc tags like @author, @version or @throws? FoReDoclet does support the @throws tag, others are simply omitted from the generated documentation. FoReDoclet will show the exceptions you specify in the @throws-tag in the exception section of the generated documentation.
For those of you unfamiliair with the @throws tag, the “documentation-generator” will interpret these as possible exceptions which the program unit can “throw back” at you.( In the “civilized” Oracle world we don’t throw things, we raise them ;-)).
Talking about making things flashy, it’s possible to include screenshots in the documentation. It’s a nice feature, will it be used in a production-enviroment? I doubt it., but it looks great.
To see a full fledged example take a look at this.
FoReDoclet is very flexible, it allows you to filter for specific forms, menu etc. These filter options are also generated in the documentation. The look and feel of the documentation can be modified to suit your needs. Inclusion of company-logo, application-logo or module-logo is all part of the deal.
Even though FoReDoclet is open source, it doesn’t include any documentation on it’s use. However you can purchase documentation. It’s available through their website.
Using FoReDoclet to create documentation will be a breeze and is fun to do….