Midrange News for the IBM i Community


Posted by: Bob Cozzi
Rogue Programmer
Cozzi Productions, Inc.
www.cozTools.com/qryfile
Chicagoland
Subprocedure Documentation Options
has no ratings.
Published: 12 Nov 2012
Revised: 23 Jan 2013 - 3665 days ago
Last viewed on: 03 Feb 2023 (4693 views) 

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.

Subprocedure Documentation Options Published by: Bob Cozzi on 12 Nov 2012 view comments(5)

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?

 

Return to midrangenews.com home page.
Sort Ascend | Descend

COMMENTS

(Sign in to Post a Comment)
Posted by: Viking
Premium member *
CA
Comment on: Subprocedure Documentation Options
Posted: 10 years 2 months 26 days 55 minutes ago
Edited: Mon, 12 Nov, 2012 at 10:34:30 (3737 days ago)

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
Posted by: bobcozzi
Site Admin ****
Chicagoland
www.cozTools.com/qryfile
Comment on: Subprocedure Documentation Options
Posted: 10 years 2 months 25 days 21 hours 28 minutes ago

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.

Posted by: bobcozzi
Site Admin ****
Chicagoland
www.cozTools.com/qryfile
Comment on: Subprocedure Documentation Options
Posted: 10 years 2 months 25 days 19 hours 1 minutes ago

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.

Posted by: Ringer
Premium member *
Comment on: Subprocedure Documentation Options
Posted: 10 years 2 months 25 days 1 hours 48 minutes ago

Nice try.

Posted by: TFisher
Premium member *
Comment on: Subprocedure Documentation Options
Posted: 10 years 2 months 24 days 4 hours 3 minutes ago
Edited: Wed, 14 Nov, 2012 at 07:04:13 (3735 days ago)

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.