× The internal search function is temporarily non-functional. The current search engine is no longer viable and we are researching alternatives.
As a stop gap measure, we are using Google's custom search engine service.
If you know of an easy to use, open source, search engine ... please contact support@midrange.com.



I really like the way JavaDoc works. I haven't used RPGDoc, as Jon suggested, but I imagine it works on the same concept.

JavaDoc reads comments and certain lines from your source file and produces HTML. The HTML is indexed in a orderly structure with a separate page for each class linked from the index. You take the output from the JavaDoc run and drop it in a directory that is served from a webserver package like HTTP Server Powered by Apache and give eveyone the URL. It's like an automatically generated wiki. Here's a public example http://javadoc.midrange.com/jtopen/index.html.

The comments follow a special structure that would work in free-form RPG. Any comment that starts with /** is considered JavaDoc. The comment must also preceed certain line types such as a class or method declaration. There are special character combinations that influence how JavaDoc will build the HTML, for instance, @param introduces your explanation of a parameter.

Most of the source editors for Java will build a JavaDoc skeleton with all the special strings for you when you type /** and press enter just before one of the line types.

JavaDoc is included in the standard jdk distribution and is therefore as free as the jdk is.

Then it's just a matter of training anyone who writes code for your shop to study your JavaDoc before writing any new code. That's always the hard part.

-----Original Message-----
From: midrange-l-bounces@xxxxxxxxxxxx [mailto:midrange-l-bounces@xxxxxxxxxxxx] On Behalf Of Sam_L
Sent: Thursday, January 05, 2012 8:19 PM
To: midrange-l@xxxxxxxxxxxx
Subject: In-house Reusable Code: Publishing and Documenting

Reusable code is a great concept, but unless you know a routine exists and what it does you can't use it.

We're a small shop and we have some reusable service programs and commands. The few heavily used commands are easy to remember, but folk forget about the rest. (I just bumped into one today that *I* created a year ago and had completely forgotten about.)

Have any of you found good answers to either of these questions for a shop with 5 or more developers?

1) How do y'all make people aware what reusable routines exist?

2) How do folk find what a reusable routine does, short of reading the code?
--
This is the Midrange Systems Technical Discussion (MIDRANGE-L) mailing list To post a message email: MIDRANGE-L@xxxxxxxxxxxx To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/midrange-l
or email: MIDRANGE-L-request@xxxxxxxxxxxx Before posting, please take a moment to review the archives at http://archive.midrange.com/midrange-l.




As an Amazon Associate we earn from qualifying purchases.

This thread ...

Replies:

Follow On AppleNews
Return to Archive home page | Return to MIDRANGE.COM home page

This mailing list archive is Copyright 1997-2024 by midrange.com and David Gibbs as a compilation work. Use of the archive is restricted to research of a business or technical nature. Any other uses are prohibited. Full details are available on our policy page. If you have questions about this, please contact [javascript protected email address].

Operating expenses for this site are earned using the Amazon Associate program and Google Adsense.