Subprocedure Documentation Options

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 - 4101 days ago
Last viewed on: 15 Apr 2024 (4990 views)

Main URL:

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?

Sort Ascend | Descend

COMMENTS

(Sign in to Post a Comment)

Posted by: Viking

Premium member *

Comment on: Subprocedure Documentation Options
Posted: 11 years 5 months 3 days 18 hours 3 minutes ago
Edited: Mon, 12 Nov, 2012 at 10:34:30 (4173 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: 11 years 5 months 3 days 14 hours 37 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: 11 years 5 months 3 days 12 hours 9 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: 11 years 5 months 2 days 18 hours 56 minutes ago

Nice try.

Posted by: TFisher

Premium member *

Comment on: Subprocedure Documentation Options
Posted: 11 years 5 months 1 days 21 hours 12 minutes ago
Edited: Wed, 14 Nov, 2012 at 07:04:13 (4171 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.