Date: Sun, 22 Jul 2007 12:24:26 -0600
Reply-To: Alan Churchill <savian001@GMAIL.COM>
Sender: "SAS(r) Discussion" <SAS-L@LISTSERV.UGA.EDU>
From: Alan Churchill <savian001@GMAIL.COM>
Subject: Re: free tool announcement: codedoc
Content-Type: text/plain; charset="us-ascii"
I like the @ sign tag for reducing the XML clutter. Perhaps we can
coordinate and come up with a reasonable set of tags for SAS comments. You
can then create a Java variant and I can have a .NET variant. Either one
should work as long as we have common tags. I would also suggest we have
common tags on sasCommunity so people can easily find both variants.
Send to the list what tags are used in codedoc. Here is what tags I am using
(based upon .NET standards):
Comment Tag
============================================================
<comment>
<code type=\"\"></code>
<remarks></remarks>
<param name=\"\" default=\"\">Description of </param>
<input name=\"\">indata</input>
<output name=\"\">outdata</output>
<returns></returns>
<example></example>
<seealso></seealso>
</comment>
Header Tag
============================================================
<header>
<company>Company Name</company>
<copyright>200x</copyright>
<name>Program Name</name>
<author>YourName</author>
<description>
description here
...and here
</description>
<usage>Description of usage</usage>
<remarks>Comment here...
</remarks>
<history>
<action initials=\"xxx\" date=\"xx/xx/xxxx\">Action taken</action>
</history>
</header>
Alan Churchill
Savian "Bridging SAS and Microsoft Technologies"
<http://www.savian.net/> www.savian.net
-----Original Message-----
From: Jeff Wright [mailto:jwright@thotwave.com]
Sent: Friday, July 20, 2007 11:59 AM
To: Alan Churchill; SAS-L@LISTSERV.VT.EDU
Subject: RE: free tool announcement: codedoc
Interesting. Codedoc also generates XML. We also have a pretty simplistic
XSL style sheet which you can use to view it as HTML.
My attitude is also the same as you: I'm more interested in seeing a
documentation standard emerge than in seeing codedoc be successful.
Our first version of codedoc used more xml markup directly in the comment
header, but then we realized it easier on the author and more readable to
have the tool turn something like
@purpose Performs some function.
into
<purpose>Performs some function.</purpose>
Our inspiration was javadoc, but we didn't try to adopt the same @TAGs as
used for Java, but instead use tags that made sense for SAS code.
--Jeff Wright
-----Original Message-----
From: Alan Churchill [mailto:savian001@gmail.com]
Sent: Friday, July 20, 2007 10:29 AM
To: Jeff Wright; SAS-L@LISTSERV.UGA.EDU
Subject: RE: free tool announcement: codedoc
Jeff,
FYI, SaviDoc uses XML, not HTML, to show comments. While related, they are
different in that HTML is strictly for display whereas XML is broader and is
used for data description. There is a better definition, I am sure, but that
is how I keep it in my brain.
SaviDoc's code comment blocks are based upon .NET standards as are the
comment pages generated.
Regardless, I support any document standards. I built SaviDoc as a means of
trying to push that area forward within the SAS community and I welcome
anything that might make that happen.
Alan
Alan Churchill
Savian "Bridging SAS and Microsoft Technologies"
www.savian.net
-----Original Message-----
From: SAS(r) Discussion [mailto:SAS-L@LISTSERV.UGA.EDU] On Behalf Of Jeff
Wright
Sent: Friday, July 20, 2007 6:32 AM
To: SAS-L@LISTSERV.UGA.EDU
Subject: free tool announcement: codedoc
Have you ever wished there was a tool that could automatically create
documentation for your SAS(r) source code?
Perhaps you've seen how the javadoc tool turns structured header comments
inside
Java source into HTML API documentation, and wished for something similar
for
SAS.
If so, codedoc may be the tool for you. Codedoc is able to read a directory
of
SAS code source files and extract documentation from header comments that
follow
simple formatting conventions. Here's an example of a codedoc header:
/* ----------------------------------------------------------------
* codedoc will start paying attention after the next line...
* <doc>
* @purpose Performs some function as a macro.
* @param DEPT - Department name (required)
* @param SUMMARY - Y/N flag to control whether this macro
* performs a summary function. Defaults to Y.
* @return none
* </doc>
* codedoc will ignore the remainder of this file...
* ----------------------------------------------------------------
*/
Codedoc is available now for free download (registration required) under the
Eclipse Public License. The distribution includes the codedoc.pl perl script
and
a sample XSL style sheet for formatting extracted documentation as HTML.
For more information or to download, please visit:
http://www.thotwave.com/products/codedoc.jsp
There is also a page at sascommunity.org:
http://www.sascommunity.org/wiki/Codedoc_-_Automated_Documentation_Tool
(currently it has no more info than this announcement)
Thanks to the sasCommunity web site, I've already learned from Alan
Churchill
that he has created a similar tool called SaviDoc:
http://www.sascommunity.org/wiki/SaviDoc
Alan's tool seems to use a slightly different, more HTML-ish format for
the header, and to directly generate HTML. Codedoc is written in perl,
which
makes it inherently cross-platform and amenable to batch operation.
However,
I've been wondering if codedoc leaves too much burden to the user to create
his or her own formatted output. There tends to be a tradeoff between
flexibility and doing something useful out of the box.
Looking forward to your feedback...
--Jeff Wright
ThotWave Technologies
