Re: Auto-building docs manual

Craig,

While I agree that the comments are critical to do a good job, most of the tools that scan source will extract information from the PIs and PRs so a minimal set of information is available anyway. The one I mentioned does not scan the source but others like Paul's do.


Jon Paris

www.partner400.com
www.SystemiDeveloper.com

On Feb 22, 2018, at 12:46 PM, Craig Richards <craig@xxxxxxxxxxxxxxxx> wrote:

Hi Martin,

I've had the same thoughts for more years than I care to remember ( we were
talking about this when I was contracted to IBM in the early 90s! and may
have even written a prototype, though it was for the telecom NZ project,
not NZ )
Obviously it's possible and it makes sense for all the reasons that javadoc
does.

I just never got around to writing my own or seeking out someone else's
solution.

That said, ( and this is no reason not to create/use such a tool ) it's
only ever going to be as good as the putting in the markup...

If I'm honest I would say the most useful documentation I've found to be my
own visio diagrams with annotations.
Well, I say Visio, but my version is Visio 4 - way before microsoft got
involved and sadly I just can't get that to run in Windows 10.
I can get it to run on my mac in my old copy of VMware Fusion but I can
never get the virtual printing to work properly.
So these days, with the extortionate price that microsoft charge for visio
it's googledocs drawings for me!

regards,
Craig

On 22 February 2018 at 16:21, Jon Paris <jon.paris@xxxxxxxxxxxxxx> wrote:

There are already several tools out there already that can do this (and
more) based on the Java Docs type comment definitions.

You can find Paul Tuohy's offering RPGLEDOC here:
http://systemideveloper.com/downloadRPGLEDOC.html <
http://systemideveloper.com/downloadRPGLEDOC.html> - I think it needs
some updates but the base is there.

Others will no doubt point you at other offerings but I don't have time to
look them up right now.

In summary - there are many things I'd rather have IBM spend their time
and money on rather than reinventing this particular wheel.


Jon Paris

www.partner400.com
www.SystemiDeveloper.com

On Feb 22, 2018, at 11:11 AM, Booth Martin <booth@xxxxxxxxxxxx> wrote:

This has been nibbling on me for a while. It seems reasonable to me but

what do I know.

Lets say that IBM provided a new kind of comment line designed to be

automatically collected at every compile and then included in a IFS
repository as a manual for that application/library/department/whatever.
Therefore there would be an automatically assembled Intranet website for
the system.

For example, say, a line which looked like:

//:index':'comment*/

Then we could specify particular comments to be used that could

document, with a built-in index, our own procedures, programs, etc that are
gathered in one useful place.

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L)

mailing list

To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related

questions.

Help support midrange.com by shopping at amazon.com with our affiliate

link: http://amzn.to/2dEadiD

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L)
mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related
questions.

Help support midrange.com by shopping at amazon.com with our affiliate
link: http://amzn.to/2dEadiD

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L) mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related questions.

Help support midrange.com by shopping at amazon.com with our affiliate link: http://amzn.to/2dEadiD