OK I have looked at the example provided about Oxygen:
http://www.richardinfo.com/examples/Richardinfo_Developer_Docs/
>From what I have seen so far, it has confirmed my fear that we may need a
more strict DynAPI language specification, or we will have to tweak oxygen
to recognize our different code blocks, or both, if we want to automate the
src to XHTML parsing.
In the above example, Oxygen only recognizes the following code blocks:
Functions and Variables
When in fact we want to recognize and document things like public methods,
public attributes, private methods, private attributes, constructors ect.
I am more than willing to learn to use Oxygen, if you think we can tweak it
to recognize the above mentioned code blocks, because I hope to document
DynAPI in more detail than just functions and variables.
>Currently there is some enthusiasm to get to work on the documentation. The
>problem is, many people will chip in the discussion, to share thoughts, but
>very few will actually do the work.
I am willing to do more than just talk about this subject. I prefer to get
down and dirty and start creating the doc opposed to just talking about
them. There is no point however in creating something and than have to
redesign it. First we have to agree on a plan of attack.
As far as I can tell we have agreed on the following:
1)We need to comment the src and we need documents on the DynAPI.
2)The documents on the DynAPI can be split into 4 modules
a)Intro
b)Reference
c)Examples
d)Tuturials
3)The reference module should be generated from the src comments, either
automatically using Oxygen or similar or manually by cut and paste
4)The documents will be on separate XHTML files tied together by a framed
interface independent of a server. Preferably utilizing DynAPI widgets to
show it off.
Things we still have to decide:
1)How detailed do we want the reference docs, will we settle for identifying
functions and variables or will we be more thorough and classify things like
constructors, public methods, etc. (I prefer the latter)
Once we agree on this we can start commenting the src
2)If we decide to go with the thorough method, we need to make an other
decision. Are going to automate the parsing of the src comments to XHTML
docs, by tweaking Oxygen or are we going to settle on cut and paste for now,
and develop the needed tweaking later?
NanoFace =;^)
-----Original Message-----
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED]]On Behalf Of Richard
Bennett
Sent: November 15, 2001 6:58 PM
To: Matt Fair; [EMAIL PROTECTED]
Subject: Re: [Dynapi-Dev] Re: Documentation Project
Hi,
Of course you can do this, but this does already exist, in the form of
Oxygen, which we have used before, it runs on windows
command-line/batch-file and Linux/server.
The only thing is, people have to be willing to learn to use it, it just
means reading the docs, and sticking to a few basic rules, for instance,
anything that comes after \todo will come on the to do list, same for \test,
always use semi-colons etc etc.
Currently there is some enthusiasm to get to work on the documentation. The
problem is, many people will chip in the discussion, to share thoughts, but
very few will actually do the work.
If you're going to attack a largish part of the project, scale the plans so
you could do it yourself, without any help, if someone does help, that's
great!
Richard
----- Original Message -----
From: "Matt Fair" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Thursday, November 15, 2001 11:30 PM
Subject: [Dynapi-Dev] Re: Documentation Project
> Hello,
> I think we should have the comments be parsed out for the
> documentation. This will simplify documenting and allow the documents
> be most up to date. When you seperate your code and documentation, they
> will eventually (like how it is now) become different unless you are
> really on top of it. So when you make a change to the code, you can
> also quickly change the documentation.
> For displaying the documentation, I agree that we should have the
> organization (menu, tree, roll over, sliding, what ever ...) with
> DynAPI. At least something that shows a little of DynAPI off.
> The Documentation should be compiled automatically, so we can make a
> server side script that compiles it *** OR *** we can make a JAVA
> program (so it will work on many platforms) and put together something
> like jsdoc (to make it similar to javadoc). I know this will be a
> different project, but hey I'm willing to start a new project on
> SourceForge if it will help the DynAPI documentation.
> Documentation is VERY important, and if we want to make DynAPI accepted
> by many developers then we need LOTS of documentation, so we need it
> easy to make good documentation of API's.
> What I did for my java project is that you can integrate the jre with
> your java program, this made it like a native C program. I used the
> FREE version of InstallAnywhere by Zerog at www.zerog.com. So people
> wouldn't have to worry about the jre with this. We could make this a
> command line base (like how javadoc is) or a GUI base application. This
> program will parse out the comments from the code and also write comment
> free code (so it will load up faster) and create the HTML/DynAPI
> documentation. A systems administrator could setup their server to use
> this program to automatically generate daily documentation.
> This is just some ideas, does anyone want to go ahead with jsdoc? I can
> do the java coding but it wouldn't hurt if I could get some help.
> Thanks,
> Matt
>
>
>
>
> _______________________________________________
> Dynapi-Dev mailing list
> [EMAIL PROTECTED]
> http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
>
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
