Using IBM i? Need to create Excel, CSV, HTML, JSON, PDF, SPOOL reports? Learn more about the fastest and least expensive tool for the job: SQL iQuery.
I'm releasing the final version of COZTOOLS next month and the question of Documentation format came up.
For the CL Commands, it was very easy. We use the online helptext (produced by press F1 when the command is prompted) as the help text. As the online help is updated, we purge the existing HTML file and the next time someone views it, the new HTML is generated from the helptext. I think it works great.
For Subprocedures, however, there isn't any automatic way to document them and their parameters, consistently, that I know of. Have any of you come across a standard way to document these things? I don't mean something you've written yourself, but rather some sort of automated methodology; perhaps something that reads the Prototype source and generates the helptext accordingly, anything like that?
I looked for something too a while back and didn't find anything so I use something I've written myself. An RPG program periodically reads through my prototype source and documents the procedures based on tags I put in my prototype header and then creates an XML and HTML document. The tags look like:
//------------------------------------------------------------- // @Name: convertTSZone // @Desc: Convert a timestamp to a different timezone // @Author: Joe Schmoe // @Return: Timestamp (Z) // @Parm: Timestamp (Z) // @Parm: From-timezone (10A) // @Parm: To-timezone (10A) // @Category: Date/Time // @Module: SRVDATTM1 //------------------------------------------------------------- D convertTSZone PR Z D fromTS Z Const D fromTimeZone 10a Const D toTimeZone 10a Const
Viking, I've seen something similar from Paul Touhy about a half dozen years ago... I suppose it is really the only logical solution.
Thanks.
Wow! I thought I almost had something automated.
The Compiler itself generates PCML which is basically just XML for every procedure. It creates an entry for every procedure and their parameters along with the definitions.
I could easily parse that XML using XML-INTO and then produce HTML from it.
But sadly, it won't properly identify stuff that is not directly Java friendly and always complains if the return value is not a 10i0 (Int4) value. So it was close, but not the golden ticket.
Nice try.
I played around with PCML a couple of years ago, it sucks. And yes, the return value thing sucks! I learned about that while learning PHP. Other than PCML there really isn't anything. You will have to create both the documentation and the tool to display the documentation yourself I am affraid.
I use help panels (*PNLGRP) for my commands and I have thought about using them for subprocedures. I am thinking that a single panel group can contain the help text for each individual subprocedure/function. A command called DSPPROHLP (Display Procedure Help) would use something like the QUIDSPP API to display the panel and allow us to find the function we are looking for, click on it, and have access to the help text, prototype, and an example.
I have been looking for something else we can use since or ulitmate solution is still far off in the future.