JavaDoc's

[ConvertFromOldNGs]

by Wilfred Verkley >> Wed, 4 Jul 2001 0:22:38 GMT

JavaDoc is a simple utility that generates a HTML help file from comments embedded in your code (which have to adhere to certain conventions). It simplifies generating code documention considerably since the documentation is maintained right with your code by the people that write/maintain it.

Has anyone done anything similar to this for Jade??? Ive seen delphi,C# and other implementations. Im slightly tempted to write one myself considering how well Jade makes its Metadata available.


Wilfred.

[ConvertFromOldNGs]

by Carl Ranson >> Wed, 4 Jul 2001 22:23:28 GMT

I have considered doing this too.....an intersting way to start would be to write a schmea -> xml converter that gave you and xml file representing your scm. Then its pretty easy to generate the documentation you want.

CR

[ConvertFromOldNGs]

by Wilfred Verkley >> Wed, 4 Jul 2001 23:24:56 GMT

I have considered doing this too.....an interesting way to start would be to write a schmea -> xml converter that gave you and xml file representing your scm. Then its pretty easy to generate the documentation you want.

Thats a good idea. Ive written a schema parser before though for an external code generator and its hard work. It might be easier to use the API within Jade to generate any XML I think (assuming Jade exposes everything you need). You could then use a stylesheet to format and display this data with very little effort.

[ConvertFromOldNGs]

by Carl Ranson >> Thu, 5 Jul 2001 5:15:17 GMT

I have considered doing this too.....an interesting way to start would be to write a schmea -> xml converter that gave you and xml file representing your scm. Then its pretty easy to generate the documentation you want.

Thats a good idea. Ive written a schema parser before though for an external code generator and its hard work. It might be easier to use the API within Jade to generate any XML I think (assuming Jade exposes everything you need). You could then use a stylesheet to format and display this data with very little effort.

Well, since they now have the _beginmethod and _endMethod tags I'd say its a lot easier to do. Depends if you need to parse the contents of each method for your documentation.

What did you have in mind for the documentation? Just a summary of features for each class?

CR

[ConvertFromOldNGs]

by Wilfred Verkley >> Thu, 5 Jul 2001 9:28:52 GMT

Well, since they now have the _beginmethod and _endMethod tags I'd say its a lot easier to do. Depends if you need to parse the contents of each method for your documentation.

What did you have in mind for the documentation? Just a summary of features for each class?

Nothing that advanced.

Just an organized list of classes and their methods and properties, possibly hyper-linked. The parser would use the class description and any comments inside the methods between two special tags e.g.

/*@ This comment will be included in the documentation */

The ulterior motive I have for not basing it on a schema extract is that if its produced from within jade using an API, I could possibly serve up the documentation "live" on the a web server using our jade-based web library. Either method would work equally well for static documents though.

[ConvertFromOldNGs]

by Warwick Hunt >> Fri, 6 Jul 2001 0:32:41 GMT

JavaDoc is a simple utility that generates a HTML help file from comments embedded in your code (which have to adhere to certain conventions). It simplifies generating code documention considerably since the documentation is maintained right with your code by the people that write/maintain it.

Has anyone done anything similar to this for Jade??? Ive seen delphi,C# and other implementations. Im slightly tempted to write one myself considering how well Jade makes its Metadata available.

Not really the same thing, but the following method creates an HTML file documenting a given class, including hyperlinks to superclass, subclasses, referenced classes and collection member classes. I run it for all subclasses of my foundation database class so that all the html files can reside in a single directory and I can browse from one class to another. Any comments?

<method follows>

buildHtml(pClass:Class; pDirectory:String);
vars
fileName : String;
htmlFile : File;
methodSet : MethodSet;
propertyColl : PropertyColl;
classProperty : Property;
propertyLength : Integer;
theMethod : Method;
type : Type;
classColl : ClassColl;
class : Class;begin

fileName := pDirectory & "\" & pClass.name & ".htm";
create htmlFile;
htmlFile.openOutput(fileName);
htmlFile.writeLine("<HTML><HEAD><TITLE>" & pClass.name & " Class</TITLE></HEAD>");
htmlFile.writeLine("<BODY><BASEFONT FACE=" & 34.Character & "Arial" & 34.Character & " SIZE=" & 34.Character & "2" & 34.Character & ">");

if pClass.immediateSuperClass = JASEntity then
htmlFile.writeLine("<H2><P ALIGN=" & 34.Character & "center" & 34.Character & "><STRONG>" & pClass.name & " Class</STRONG></H2></P>");
else
htmlFile.writeLine("<H2><P ALIGN=" & 34.Character & "center" & 34.Character & "><STRONG>" & pClass.name &
" Class (Subclass of <A HREF=" & pClass.immediateSuperClass.name & ".htm><B>" &
pClass.immediateSuperClass.name & ")</B></A></STRONG></H2></P>");
endif;
create methodSet transient;

htmlFile.writeLine(pClass.getText);

htmlFile.writeLine("<H2><STRONG>Attributes</STRONG></H2><BR>");
propertyColl := pClass.allProperties; // Find the attributes for this class
htmlFile.writeLine("<TABLE WIDTH=" & 34.Character & "100%" & 34.Character & ">");
htmlFile.writeLine("<TR><TD><STRONG>Attribute</STRONG></TD><TD><STRONG>Type< /STRONG></TD><TD><STRONG>Length</STRONG></TD></TR>");

foreach classProperty in propertyColl do
if classProperty.getName <> "_persistentImpRefs" and classProperty.getName <> "_transientImpRefs" then

htmlFile.writeLine("<TR>");
htmlFile.writeLine("<TD>" & classProperty.getName & "</TD>");
type:=classProperty.getType;
if type.isKindOf(PrimType) then
htmlFile.writeLine("<TD>" & type.getName & "</TD>");
elseif type.isKindOf(CollClass) then
if type.CollClass.memberType.isJasEntity then
htmlFile.writeLine("<TD>" & type.getName &
" (<A HREF=" & type.CollClass.memberType.getName &
".htm><B>" & type.CollClass.memberType.getName & "</B></A>)</TD>");
else
htmlFile.writeLine("<TD>" & type.getName & "</TD>");
endif;
elseif type.Class.isSubclassOf(JASEntity) then
htmlFile.writeLine("<TD><A HREF=" & type.getName & ".htm><B>" & type.getName & "</B></A></TD>");
else
htmlFile.writeLine("<TD>" & type.getName & "</TD>");
endif;

propertyLength := classProperty.getLength;

if classProperty.getType.getName = "String" then
if propertyLength = -1 then
htmlFile.writeLine("<TD>Maximum</TD>");
else
htmlFile.writeLine("<TD>" & (propertyLength - 1).String & "</TD>");
endif;
else
htmlFile.writeLine("<TD></TD>");//("<TD>" & propertyLength.String & "</TD>");
endif;

htmlFile.writeLine("</TR>");
endif;
endforeach;

htmlFile.writeLine("</TABLE><BR>");

if pClass.hasSubclasses then
htmlFile.writeLine("<H2><STRONG>SubClasses</STRONG></H2><BR>");
create classColl transient;
pClass.allSubclasses(classColl);

foreach class in classColl do
htmlFile.writeLine("<A HREF=" & class.getName & ".htm><B>" & class.getName & "</B></A><BR>");
endforeach;
endif;

htmlFile.writeLine("<H2><STRONG>Methods</STRONG></H2><BR>");
pClass.allMethods(methodSet); // Find the methods for this class.

foreach theMethod in methodSet do
htmlFile.writeLine("<STRONG>" & theMethod.getName & "</STRONG><BR><TT>"); htmlFile.writeLine(theMethod.makeHeader & ";</TT><BR><BR>");
endforeach;

htmlFile.writeLine("</BODY></HTML>");
epilog
htmlFile.close();
delete htmlFile;
delete methodSet;
delete classColl;
end;

[ConvertFromOldNGs]

by Carl Ranson >> Fri, 6 Jul 2001 1:14:15 GMT

That does it...now I'm inspired.

I'm going to write a xml version of this (assuming you have no objections, Warwick). I'll post the resulting code next week.

If either of you chaps (or anyone else for that matter) would like to collaborate on a system for extracting documentation from Jade, send me an email.

Cheers,
CR Carl.Ranson@unify.co.nz

[ConvertFromOldNGs]

by Carl Ranson >> Fri, 6 Jul 2001 4:19:47 GMT

Pretty easy really (although I did simplify for some of the specifics in Warwick's code). Code & results attached.

The next step, of course, is to write an xslt to present this in a nice readable format.

CR

<?xml version="1.0" ?>
- <JADECLASS ID="2282">
<NAME>Root</NAME>
<TEXT />
- <PROPERTY>
<NAME>allCodes</NAME>
<TYPE>CodeArray</TYPE>
</PROPERTY>
- <PROPERTY>
<NAME>allPeople</NAME>
<TYPE>PersonDict</TYPE>
</PROPERTY>
- <PROPERTY>
<NAME>allTasks</NAME>
<TYPE>TaskByPersonWhenDict</TYPE>
</PROPERTY>
- <PROPERTY>
<NAME>customColors</NAME>
<TYPE>IntegerArray</TYPE>
</PROPERTY>
- <METHOD>
<NAME>getRootCodes</NAME>
<HEADER>getRootCodes(ca : CodeArray input);</HEADER>
</METHOD>
- <METHOD>
<NAME>dumpToCSV</NAME>
<HEADER>dumpToCSV(fileName : String);</HEADER>
</METHOD>
</JADECLASS>

buildXML(pClass:Class; pDirectory:String);
constants
XMLHeader = '<?xml version="1.0"?>';
vars
fileName : String;
htmlFile : File;
methodSet : MethodSet;
propertyColl : PropertyColl;
classProperty : Property;
propertyLength : Integer;
theMethod : Method;
type : Type;
classColl : ClassColl;
class : Class;begin

fileName := pDirectory & "\" & pClass.name & ".xml";
create htmlFile;
htmlFile.openOutput(fileName);
htmlFile.writeLine(XMLHeader);
htmlFile.writeLine('<JADECLASS ID="' & pClass.number.String & '">');
htmlFile.writeLine("<NAME>" & pClass.name & "</NAME>");
create methodSet transient;

htmlFile.writeLine('<TEXT>' & pClass.getText & '</TEXT>');

propertyColl := pClass.allProperties; // Find the attributes for this class

foreach classProperty in propertyColl do
if classProperty.getName <> "_persistentImpRefs" and classProperty.getName <> "_transientImpRefs" then

htmlFile.writeLine("<PROPERTY><NAME>" & classProperty.getName & "</NAME>");
type:=classProperty.getType;
htmlFile.writeLine("<TYPE>" & type.getName & "</TYPE>");

propertyLength := classProperty.getLength;

if classProperty.getType.getName = "String" then
if propertyLength = -1 then
htmlFile.writeLine("<LENGTH>Maximum</LENGTH>");
else
htmlFile.writeLine("<LENGTH>" & (propertyLength - 1).String & "</LENGTH>");
endif;
else
endif;

htmlFile.writeLine("</PROPERTY>");
endif;
endforeach;

if pClass.hasSubclasses then
htmlFile.writeLine("<H2><STRONG>SubClasses</STRONG></H2><BR>");
create classColl transient;
pClass.allSubclasses(classColl);

foreach class in classColl do
htmlFile.writeLine("<A HREF=" & class.getName & ".htm><B>" & class.getName & "</B></A><BR>");
endforeach;
endif;

pClass.allMethods(methodSet); // Find the methods for this class.

foreach theMethod in methodSet do
htmlFile.writeLine("<METHOD><NAME>" & theMethod.getName & "</NAME><HEADER>");
htmlFile.writeLine(theMethod.makeHeader & ";</HEADER></METHOD>");
endforeach;

htmlFile.writeLine("</JADECLASS>");
epilog
htmlFile.close();
delete htmlFile;
delete methodSet;
delete classColl;
end;

[ConvertFromOldNGs]

by Wilfred Verkley >> Sun, 8 Jul 2001 21:17:14 GMT

Based on Warwicks excellent example i created an dynamic web page to produce the same kind of XML that Carl produced in his example. If were going to collaborate, we should decide on a standard XML Schema on this stuff. An XSL stylesheet could then convert the documentation based on whether its been stored statically in an HTML page, or dynamically served up (probably only just a minor difference in the HTML "hrefs").


<%@ Language=JadeScript%>
<%
vars
class : Class;begin

class := request.queryString ("class").asOid.Class;
response.setHeader ("Content-Type", "text/xml");
%>
<?xml version="1.0"?>
<CLASS name="<%=class.name%>" oid="<%=class.getOidString%>">
<TEXT><%=class.getText%></TEXT>
<%
// Find the superclass for this class
if class.getSuperclass <> null then
%>
<SUPERCLASS name="<%=class.getSuperclass.name%>" oid="<%=class.getSuperclass.getOidString%>"/>
<%
endif;
// blah blah blah
end;