nrxdoc annoucement

[Peter Heuchert]

nrxdoc is a documentation generator for NetRexx like javadoc for Java.
It generates API documentation in HTML format, for an individual NetRexx
source file, or for all NetRexx files in a directory tree.

nrxdoc is parsing source files and analysing the code. Special documentation
comments are linked to class, method, or property definitions. The HTML
documentation
includes references to the Java syntax, so the cooperation with Java
programmers is
supported.

You can find nrxdoc on http://servicepac.mainz.ibm.de/nrxdoc

Any comments or requests are welcome.

Peter Heuchert                                             pheuch at de.ibm.com
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>

[Martin Lafaix]

What about adding a shortcut for one-line documentation comments
in NetRexx, to enhance code readibility?  I would suggest '++'
which fits well with the current '--' comment shortcut (and
reminds nicely of ScratchPad/Axiom :-).

For example, with Peter's WorldClock example:

   ++ WordClock -- an applet that shows the time in English.
   ++
   ++ Based on the ancient QTIME.REXX, and typical Java applets.
   ++ @param face the font face to use
   ++ @param size the font size to use
   ++
   ++ @author Mike Cowlishaw, December 1979 - January 1985.
   
   class WordClock extends Applet implements Runnable
   
   timer=Thread null /* the timer thread */
   offsetx; offsety /* text position */
   now /* current time */
   
   ++ Initialize the applet
   method init

It wouldn't have to replace current '/** ... */', just complement
it.

Opinions?


Martin
--
[hidden email]
Team OS/2
http://wwwi3s.unice.fr/~lafaix

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>

[William H. Geiger III-2]

-----BEGIN PGP SIGNED MESSAGE-----

In <199712040444.XAA021.92@YOUR-HOST-NAME>, on 12/03/97
   at 06:32 PM, "Martin Lafaix" <[hidden email]> said:


>What about adding a shortcut for one-line documentation comments  in
>NetRexx, to enhance code readibility?  I would suggest '++'  which fits
>well with the current '--' comment shortcut (and  reminds nicely of
>ScratchPad/Axiom :-).

>For example, with Peter's WorldClock example:

>   ++ WordClock -- an applet that shows the time in English.
>   ++
>   ++ Based on the ancient QTIME.REXX, and typical Java applets.
>   ++ @param face the font face to use
>   ++ @param size the font size to use
>   ++
>   ++ @author Mike Cowlishaw, December 1979 - January 1985.
>  
>   class WordClock extends Applet implements Runnable
>  
>   timer=Thread null /* the timer thread */
>   offsetx; offsety /* text position */
>   now /* current time */
>  
>   ++ Initialize the applet
>   method init

>It wouldn't have to replace current '/** ... */', just complement it.

>Opinions?

Anyone try this out with current RCS which use '+' & '-' in their diff
files?

If anything I would prefer using the '//' that C++ uses at least I know
that it woun't break anything.

- --
- ---------------------------------------------------------------
William H. Geiger III  http://users.invweb.net/~whgiii
Geiger Consulting    Cooking With Warp 4.0

Author of E-Secure - PGP Front End for MR/2 Ice
PGP & MR/2 the only way for secure e-mail.
OS/2 PGP 2.6.3a at: http://users.invweb.net/~whgiii/pgpmr2.html                       
- ---------------------------------------------------------------

-----BEGIN PGP SIGNATURE-----
Version: 2.6.3a-sha1
Charset: cp850
Comment: Registered_User_E-Secure_v1.1b1_ES000000

iQCVAwUBNIaR149Co1n+aLhhAQJYyQP9EanUHjsnBIRJi6I+EoVOrRdaggwsrrNl
tRbgiWjL3aSNpUME80Eg6Diq4Fnvipe7aeQOZkWle273+yqocYel+5U5659S9Cqv
ZgyysInbHnDUCoSOFLiRpY6oNccB++iEOjm1npuhmMeHEKlbaKIbnNi6BCeFTm5k
qO/9Ni1+QRw=
=jHVf
-----END PGP SIGNATURE-----

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>

[Peter Heuchert]

Sorry, but I can see no advantage of such a syntax. It is no enhancement,
because the /** */ does the same, and requieres a change of
the NetRexx language. I don't believe that Mike would like this.

I used as much as possible the original javadoc syntax. Examples for this
are the @param and the other parameters.

Online comments can be used when defining properties:

/** This is a test class
*   to visualize the documentation features
*/
class test
  Properties inheritable
    test1 = Rexx  -- this is the first test variable
    ...

The comment is used for the documentation what is different to javadoc
implementation.

Peter Heuchert
[hidden email]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>

[Martin Lafaix]

> From: "William H. Geiger III" <[hidden email]>
> If anything I would prefer using the '//' that C++ uses at least I know
> that it woun't break anything.

Well, // is a NetRexx operator (remainder).  So using it would
certainly break something...


Martin
--
[hidden email]
Team OS/2
http://wwwi3s.unice.fr/~lafaix

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>

[Martin Lafaix]

> From: "Peter Heuchert" <[hidden email]>
> Sorry, but I can see no advantage of such a syntax.  It is no
> enhancement, because the /** */ does the same, and requieres a
> change of the NetRexx language.

My point is not to remove /** */.  It is more about readability.
(It's easy to confuse it with /* */ or to mistype it.)  It indeed
requires a change of the NetRexx language (but induces no
incompatibility since ++ is explicitly documented as being an
invalid sequence).

> Online comments can be used when defining properties:
>
>     test1 = Rexx  -- this is the first test variable
>
> The comment is used for the documentation what is different to javadoc
> implementation.

I interpret this as yet another reason to adopt a new online
documentation comment delimiter (but then I'm biased :-).  That
is, I do have comments as given above in my sources that I don't
want to be included in documentation.


Martin, lobbyist wannabe
--
[hidden email]
Team OS/2
http://wwwi3s.unice.fr/~lafaix

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>

[William H. Geiger III-2]

-----BEGIN PGP SIGNED MESSAGE-----

In <199712041728.MAA000.38@YOUR-HOST-NAME>, on 12/04/97
   at 12:26 PM, "Martin Lafaix" <[hidden email]> said:


>> From: "William H. Geiger III" <[hidden email]>
>> If anything I would prefer using the '//' that C++ uses at least I know
>> that it woun't break anything.

>Well, // is a NetRexx operator (remainder).  So using it would  certainly
>break something...

Yep I forgot about that. <sigh> I guess that is what I get for writting
messages after being up all night.

- --
- ---------------------------------------------------------------
William H. Geiger III  http://users.invweb.net/~whgiii
Geiger Consulting    Cooking With Warp 4.0

Author of E-Secure - PGP Front End for MR/2 Ice
PGP & MR/2 the only way for secure e-mail.
OS/2 PGP 2.6.3a at: http://users.invweb.net/~whgiii/pgpmr2.html                       
- ---------------------------------------------------------------

-----BEGIN PGP SIGNATURE-----
Version: 2.6.3a-sha1
Charset: cp850
Comment: Registered_User_E-Secure_v1.1b1_ES000000

iQCVAwUBNIbBoI9Co1n+aLhhAQJXfAQAyrQa2yZhRtoQEOAgVNPo1mjmwHx2jS5D
9dkY3sk79pO02PuGh4bPTnSyHFdoiAQ9ENqk4uePhfTDh5fvLC4nOE0nwEzHHMuC
N1TDXQlBHNNB/oPcoAtYnl6f4NW1xqHXbOiyZmEOnrE+ajDfw8dVBj8i8lmXCyVb
OR4YwhCZKEA=
=UG+z
-----END PGP SIGNATURE-----

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To unsubscribe from this mailing list ( ibm-netrexx ), please send a note to
[hidden email]
with the following message in the body of the note
unsubscribe ibm-netrexx <e-mail address>