>I presume it's a little quite around the documentation topic because
>everyone's busy writing the docs :o)
Accually I have been coding the documentation structure as I have originally
outlined with the different modules (intro, reference, examples, tuturials).
I don't have enough coded to provide a glimps yet, but as soon as I do
(hopefully after the weekend) I will zip it up and distribute it for review.
The first draft will be just a plain jane no bells or whistles structural
prototype.
>I don't think it's feasible to update two versions of our source-code, and
>to be honest, the docs generated from the Java version of our source code
>did not actually help me understand the DynAPI, because I'm not so familiar
>with the Java syntax.
So my fear has been realized. I have not played with Doxygen yet, but from
what you have been able to produce from it, it does not seem promising. It
might be more trouble than it's worth. If we have to have dual source, one
in JS and one in Java, we might as well just have it in JS and cut and paste
the comments into the docs, for now. Later we could create a pearl script to
create the docs from our JS files.
Instead of comming up with a strict language specification for our DynAPI,
it might be easier to just declare blocks of code in our comments as a
constructor for example:
/**Constructor
This constructor instantiates widget x
*/
WidgetX.prototype = new DynLayer();
Than we can create a perl program that creates the docs, from these
declarations. It would look for things like '/**Constructor' and produce
<XHTML>.
But this is a secondary project, that will only help us with automating the
reference module of our docs. For now we can just create the doc strucure
(which I started) and comment the src.
To comment the src, we need a commenting standard, and we should try to
accomodate our future Perl Automator. (If we agree to go this route)
What types of blocks do we want to identify? (ie Cosntructor, Public
Methods, Private Methods, etc.)
Some standards I think we should have:
1) The first line of comment for a script block will be the declaration:
'/**Constructor' No space between /** and the declaration
2) Following the declaration line would be the description of the code
block:
'This constructor instantiates widget x'
3) Following the description would be the comment closer token on a new line
'*/'
4a) The very next line would be the function or property
'WidgetX.prototype = new DynLayer();'
4b) alternatly we could recreate the function in a simplied version as part
of the comment. ie instead of using the actual code for the document:
DynLayer.prototype.getClip=function() {
we could create a simple version as part of the comment:
getClip()
and use it as part of the documentation. This would make the document more
readable
NanoFace =;^)
-----Original Message-----
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED]]On Behalf Of Richard
Bennett
Sent: November 21, 2001 9:29 AM
To: [EMAIL PROTECTED]
Subject: [Dynapi-Dev] documentation
hi,
I presume it's a little quite around the documentation topic because
everyone's busy writing the docs :o)
I did some testing on Doxygen.
I don't think it's feasible to update two versions of our source-code, and
to be honest, the docs generated from the Java version of our source code
did not actually help me understand the DynAPI, because I'm not so familiar
with the Java syntax.
So I did a test to see if we could us Doxygen to create documentation from
our standard commented source-code.
For those wanting constructor/destructor and Java::syntax it might be
disappointing, to me it looks readable for Javascript coders.
I just did the DynObject part of dynapi.js, and I tried all Doxygen syntax
that we could use, so not all comments are genuine - some are simply to test
the output.
I did 3 manual edits to create this, all the rest is done automatically.
Have a look at this:
http://www.richardinfo.com/examples/apiNew/
or if the redirect is slow:
http://www.your-site.com/~rinfo//examples/apiNew/
This is the frames version, the same code can be used without frames, using
the page-top menu:
http://www.your-site.com/~rinfo//examples/apiNew/main.html
the two main sections are the source code:
http://www.your-site.com/~rinfo//examples/apiNew/dynapi_8js-source.html
and the documentation:
http://www.your-site.com/~rinfo//examples/apiNew/dynapi_8js.html
What I want to know is, if this looks like it could be of use to people
learning the DynAPI source code, if so, I'll write some documentation on
using Doxygen with DynAPI, so the commenting can be done in the same style,
by various list members.
If not, then I think we'd best simply comment the dynapi source-code
clearly, and use that as documentation.
Some feedback on this would be great...
Cheers,
Richard.
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/[email protected]/
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/[email protected]/
