Yeah, any way you look at it, there's some work to do to achieve better
docs. :p Just trying to understand the situation and weigh the
uptions.
Leif
----- Original Message -----
From: "Peter Romianowski" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Thursday, June 10, 2004 11:56 AM
Subject: Re: [Dynapi-Dev] Suggestions
> Hi,
>
> I think the better way would be to stick to the "p"-thing and modify
JsDoc.
> (or (later) rewrite JsDoc in Java or whatever) The should be easy
enough
> because JsDoc uses a bunch of regexp.
>
> Converting the dynapi would be hell! ;)
>
> Regards
> Peter
>
> Leif W wrote:
> > What was the basis of the original decision to use "p" instead of
the
> > "standard" way? Was it for performance? Was it before there was a
> > standard? If it's for performance, it might not be good to change
it in
> > the release code. But could development code be written in standard
> > format, then be converted to use "p" everywhere for production via
some
> > util? Would it bee too insane to approach it this way? Is there a
> > better way?
> >
> > Leif
> >
> > ----- Original Message -----
> > From: "Doug Melvin" <[EMAIL PROTECTED]>
> > To: <[EMAIL PROTECTED]>
> > Sent: Thursday, June 10, 2004 10:58 AM
> > Subject: Re: [Dynapi-Dev] Suggestions
> >
> >
> >
> >>YEs! let's get a cvs update!
> >>There have been a few fizes as of late.
> >>
> >>As for the prototyping, switching it over to the "standard" way
would
> >
> > now be
> >
> >>too difficult..
> >>(i don't think) I could dedicate myself to that conversion, but
> >
> > someone will
> >
> >>have to commit it
> >>(i have been trying to get sourceforge to sent me my damned password
> >
> > for 3
> >
> >>years now, maybe it's fixed now?)
> >>
> >>cheers
> >>----- Original Message -----
> >>From: "Peter Romianowski" <[EMAIL PROTECTED]>
> >>To: <[EMAIL PROTECTED]>
> >>Sent: Thursday, June 10, 2004 10:12 AM
> >>Subject: Re: [Dynapi-Dev] Suggestions
> >>
> >>
> >>
> >>>Hi,
> >>>
> >>>just some short comments on JsDoc.
> >>>I am using JsDoc for quite a while now and it works well for me.
But
> >
> > using
> >
> >>it for the (current)
> >>
> >>>dynapi codebase brings a lot of problems because of the way dynapi
> >
> > handles
> >
> >>to definition of classes.
> >>
> >>>JsDoc only "accepts" classes (prototypes) written the "standard"
> >
> > way:
> >
> >>>function MyClass() {
> >>>}
> >>>
> >>>// Superclasses must be defined like this
> >>>MyClass.prototype = new MySuperClass();
> >>>
> >>>// Methods like this:
> >>>MyClass.prototype.myFunction=function() {
> >>>}
> >>>
> >>>The "dynapi way" is this:
> >>>
> >>>function MyDynapiClass() {
> >>> // Inheritance (I think JsDoc recognizes this too)
> >>> this.MyDynapiSuperClass=MyDynapiSuperClass;
> >>> this.MyDynapiSuperClass();
> >>>}
> >>>
> >>>var p = dynapi.setPrototype ('MyDynapiClass',
'MyDynapiSuperClass');
> >>>
> >>>p.myFunction=function() {
> >>>}
> >>>
> >>>The problem is that methods are declared using the "p-variable".
> >
> > This way
> >
> >>JsDoc does not regocnize
> >>
> >>>the class-methods. One would have to patch JsDoc or rewrite the
> >
> > dynapi...
> >
> >>>Generelly I really like the idea of using JsDoc (I use it ;) This
> >
> > leads to
> >
> >>much cleaner code and helps
> >>
> >>>a lot understanding the code (because it includes comments then).
> >>>
> >>> >> Of course, you still have
> >>> >> to comment your code at some level, which takes time, energy
and
> >>> >> discipline. :p
> >>>
> >>>But it buys you a lot! I remember the pain I had understanding the
> >
> > dynapi
> >
> >>completely. There are concepts
> >>
> >>>(the "old" Stylemanager, SODA) that are really not so easy to
> >
> > understand
> >
> >>in the first place. Missing documentation
> >>
> >>>makes it even harder.
> >>>
> >>>As soon as the "new" DynAPI 3.0 is in CVS I really would like to
> >>
> >>contribute some of my extension and help out
> >>
> >>>in documentation. Perhaps(!) I will have a deeper look into JsDoc
to
> >>
> >>extend it. The idea of a Java-based
> >>
> >>>javascript-javadoc is great. If someone has the time starting such
a
> >>
> >>project I would be a happy contributer
> >>
> >>>to it! ;) Perhaps looking at Rhino (http://www.mozilla.org/rhino/)
> >
> > or
> >
> >>another Java-based JS-Interpretor could
> >>
> >>>help here...
> >>>
> >>>Just my 2 cents,
> >>>
> >>>Peter
> >>>
> >>>
> >>>
> >>>
> >>>
> >>>Rob Butler wrote:
> >>>
> >>>
> >>>>Hey Leif,
> >>>>
> >>>>Nice to (virtually) meet you.
> >>>>
> >>>>I don't think that JSdoc will parse / JavaDoc anything but
> >
> > Javascript at
> >
> >>this point. But similar tools could possibly be built for those
other
> >>languages. Other people who use those languages all the time may
> >
> > already
> >
> >>have done that. But if we at least get the Dynapi Javascript code
> >
> > Javadoc'd
> >
> >>that would be a good thing, since it's the lion's share of the code,
> >
> > and
> >
> >>what people are going to use the most.
> >>
> >>>>JSdoc uses a Perl templating framework, so if need be the
> >
> > templates
> >
> >>could be modified to perform custom output / html generation. I
would
> >
> > say
> >
> >>to use them as they are initially and modify the templates later as
> >
> > Dynapi
> >
> >>needs. The JSdoc tool seems to build a collection of object tree
> >
> > structures
> >
> >>that contain all the information about the code. Then the
collection
> >
> > of
> >
> >>object tree structures are used in the templates to generate the
HTML.
> >
> > This
> >
> >>is great because after the parsing stage all the collected info is
> >
> > available
> >
> >>for use in any way you want during the html generation stage in the
> >>templates.
> >>
> >>>>If JSdoc were re-done in Java (again preferably as an ant task) I
> >
> > would
> >
> >>suggest using either Velocity or Freemarker as a templating
framework
> >
> > to do
> >
> >>the same thing as the Perl templating framework. The "port" to Java
> >
> > could
> >
> >>probably be done in a few parts & stages. One part would work on
> >
> > getting a
> >
> >>Java version of the parsing system that builds the collection of
tree
> >>structures. The other part would work on re-creating the Perl
> >
> > templates in
> >
> >>Velocity or Freemarker. The conversion of the templates would
> >
> > probably be
> >
> >>fairly easy... Just take the Perl templates and convert the syntax
> >
> > for
> >
> >>substitution to use the velocity/freemarker syntax instead of the
Perl
> >>syntax. Of course before doing that we would have to get permission
> >
> > from
> >
> >>the JSdoc developers if we wanted to use a different license than
GPL.
> >
> > If
> >
> >>we did all this work to build an ant task to JavaDoc JavaScript it
> >
> > would be
> >
> >>good if we did it under and Apache license, as then it could be
> >
> > incorporated
> >
> >>into Ant itself. The
> >>
> >>>ant group could potentially take over development / maintainance at
> >
> > that
> >
> >>point too, since it could / would become part of Ant's core.
> >>
> >>>>Later
> >>>>Rob
> >>>>
> >>>>PS. Paragraphs -- They're a good thing. :)
> >>>>
> >>>>
> >>>>
> >>>>>Hmm, I'm only a half-peon contributor but I think I remember
> >
> > hearing
> >
> >>>>>about or looking at the jsdoc project. Wouldn't that be cool, to
> >
> > just
> >
> >>>>>be bumping along in your code, modifying things and dropping some
> >>>>>comments, and click a button and generate new docs that are up to
> >
> > date?
> >
> >>>>>That would really combat the doc lag problem. Of course, you
> >
> > still have
> >
> >>>>>to comment your code at some level, which takes time, energy and
> >>>>>discipline. :p Sounds like a good idea though, and something I
> >
> > could
> >
> >>>>>help with, if only involved moving text from the current docs
back
> >
> > into
> >
> >>>>>the source. But I might not know if the docs are /correct/.
That
> >
> > could
> >
> >>>>>be easily tackled as a separate problem though, first convert,
> >
> > then
> >
> >>>>>correct. Ideally it'd be done in one go. But if it takes the
> >
> > first
> >
> >>>>>step to motivate someone to do the second step, then it'd be
worth
> >
> > it in
> >
> >>>>>the end IMO. But, eh, what about custom formatting of the
> >
> > webpages and
> >
> >>>>>such? Can the JSDoc treat comments as sort of a "database"
entry,
> >>>>>allowing tokens and their values to be assigned to variables, and
> >
> > then
> >
> >>>>>use templates to replace with the variables and values? And what
> >
> > about
> >
> >>>>>the ASP (JScript and VBScript), Perl, PHP, (TCL, Scheme, Java,
> >
> > etc.)
> >
> >>>>>sources for the server-side scripts like IOElement and SODA? Can
> >
> > JSDoc
> >
> >>>>>support other comment structures, like Perl's '#'?
> >>>>>
> >>>>>Leif
> >>>>>
> >>>>>----- Original Message -----
> >>>>>From: "Rob Butler" <[EMAIL PROTECTED]>
> >>>>>To: <[EMAIL PROTECTED]>
> >>>>>Sent: Wednesday, June 09, 2004 9:27 PM
> >>>>>Subject: [Dynapi-Dev] Suggestions
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>>Hello,
> >>>>>>
> >>>>>>Dynapi 3.0 looks real nice. I hope to use it in a variety of
> >
> > open
> >
> >>>>>source &
> >>>>>
> >>>>>>commercial projects that I will be developing shortly. I hope
to
> >>>>>
> >>>>>contribute
> >>>>>
> >>>>>
> >>>>>>back to the Dynapi project as well. On that front I have a few
> >>>>>
> >>>>>suggestions.
> >>>>>
> >>>>>
> >>>>>>I really like having a Javascript compressor and it's great to
> >
> > see you
> >
> >>>>>have
> >>>>>
> >>>>>
> >>>>>>implemented one in Java. It would be great if the compressor
> >
> > could be
> >
> >>>>>>extended to be an ant task as well as a stand alone executable.
> >>>>>
> >>>>>Instead of
> >>>>>
> >>>>>
> >>>>>>just wrapping the existing Java class as an ant task, I would
> >>>>>
> >>>>>recommend
> >>>>>
> >>>>>
> >>>>>>building the ant task to work in the "ant way" in that it
doesn't
> >
> > use
> >
> >>>>>a
> >>>>>
> >>>>>
> >>>>>>separate config file, and accepts parameters & settings from the
> >
> > ant
> >
> >>>>>script.
> >>>>>
> >>>>>
> >>>>>>If I get some spare time between my other projects I could
> >
> > potentially
> >
> >>>>>help
> >>>>>
> >>>>>
> >>>>>>with this, but I just wanted to get the thought out there if
> >
> > someone
> >
> >>>>>else
> >>>>>
> >>>>>
> >>>>>>wanted to run with it.
> >>>>>>
> >>>>>>Regarding the Javascript compressor, I think it's pretty neat
how
> >
> > you
> >
> >>>>>have
> >>>>>
> >>>>>
> >>>>>>it doing runtime inclusion / exclusion of scripts in a single
> >
> > file
> >
> >>>>>instead
> >>>>>
> >>>>>
> >>>>>>of needing to pull in multiple smaller files. However, I think
> >
> > the
> >
> >>>>>larger
> >>>>>
> >>>>>
> >>>>>>file size is probably more of a negative than the separate small
> >>>>>
> >>>>>files.
> >>>>>
> >>>>>
> >>>>>>Browsers are pretty well optimized for pulling in lots of little
> >
> > files
> >
> >>>>>>because everything on the web is a separate small file. I just
> >
> > point
> >
> >>>>>this
> >>>>>
> >>>>>
> >>>>>>out because if an ant based Javascript compressor were built I
> >
> > think
> >
> >>>>>this
> >>>>>
> >>>>>
> >>>>>>feature could be left out without too much of a negative impact
> >>>>>
> >>>>>compared to
> >>>>>
> >>>>>
> >>>>>>the existing applications featureset.
> >>>>>>
> >>>>>>Like most open source projects the documentation in Dynapi seems
> >
> > to be
> >
> >>>>>>lagging the code's capabilities. I was considering developing
my
> >
> > own
> >
> >>>>>API
> >>>>>
> >>>>>
> >>>>>>similar to Dynapi (thanks for saving me a ton of work) and knew
> >>>>>>documentation would be difficult to keep up with, and being a
> >
> > Java
> >
> >>>>>developer
> >>>>>
> >>>>>
> >>>>>>I really like JavaDoc. So I looked for a Javascript Javadoc
tool
> >
> > and
> >
> >>>>>found
> >>>>>
> >>>>>
> >>>>>>one: http://jsdoc.sourceforge.net/ This tool is written in Perl
> >>>>>
> >>>>>(which is
> >>>>>
> >>>>>
> >>>>>>ok, I would just prefer Java so it could be an Ant task without
> >>>>>
> >>>>>wrapping a
> >>>>>
> >>>>>
> >>>>>>separate perl module). Perhaps Dynapi could adopt using this
> >
> > tool to
> >
> >>>>>>document it's internals? I would also be interested in
> >
> > developing a
> >
> >>>>>Java
> >>>>>
> >>>>>
> >>>>>>based ant task to do Javascript Javadoc generation. Perhaps if
> >
> > you
> >
> >>>>>all
> >>>>>
> >>>>>
> >>>>>>think it is a good idea to use this tool, we could contact the
> >
> > JSDoc
> >
> >>>>>>developers and see if they would be interested in developing a
> >
> > Java
> >
> >>>>>port of
> >>>>>
> >>>>>
> >>>>>>their tool as an ant task. Perhaps JSDoc & Dynapi could join
> >
> > forces
> >
> >>>>>since
> >>>>>
> >>>>>
> >>>>>>both groups are obviously interested in Javascript, and both
have
> >>>>>
> >>>>>developed
> >>>>>
> >>>>>
> >>>>>>a Javascript "build time" tool that compliment each other?
> >>>>>>
> >>>>>>Just some thoughts. Looking forward to doing good things with /
> >>>>>>contributing to Dynapi.
> >>>>>>
> >>>>>>Later
> >>>>>>Rob
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>-------------------------------------------------------
> >>>>>>This SF.Net email is sponsored by: GNOME Foundation
> >>>>>>Hackers Unite! GUADEC: The world's #1 Open Source Desktop
Event.
> >>>>>>GNOME Users and Developers European Conference, 28-30th June in
> >
> > Norway
> >
> >>>>>>http://2004/guadec.org
> >>>>>>_______________________________________________
> >>>>>>Dynapi-Dev mailing list
> >>>>>>[EMAIL PROTECTED]
> >>>>>>http://www.mail-archive.com/[EMAIL PROTECTED]/
> >>>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>-------------------------------------------------------
> >>>>>This SF.Net email is sponsored by: GNOME Foundation
> >>>>>Hackers Unite! GUADEC: The world's #1 Open Source Desktop Event.
> >>>>>GNOME Users and Developers European Conference, 28-30th June in
> >
> > Norway
> >
> >>>>>http://2004/guadec.org
> >>>>>_______________________________________________
> >>>>>Dynapi-Dev mailing list
> >>>>>[EMAIL PROTECTED]
> >>>>>http://www.mail-archive.com/[EMAIL PROTECTED]/
> >>>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>-------------------------------------------------------
> >>>>This SF.Net email is sponsored by: GNOME Foundation
> >>>>Hackers Unite! GUADEC: The world's #1 Open Source Desktop Event.
> >>>>GNOME Users and Developers European Conference, 28-30th June in
> >
> > Norway
> >
> >>>>http://2004/guadec.org
> >>>>_______________________________________________
> >>>>Dynapi-Dev mailing list
> >>>>[EMAIL PROTECTED]
> >>>>http://www.mail-archive.com/[EMAIL PROTECTED]/
> >>>>
> >>>>
> >>>
> >>>
> >>>-------------------------------------------------------
> >>>This SF.Net email is sponsored by: GNOME Foundation
> >>>Hackers Unite! GUADEC: The world's #1 Open Source Desktop Event.
> >>>GNOME Users and Developers European Conference, 28-30th June in
> >
> > Norway
> >
> >>>http://2004/guadec.org
> >>>_______________________________________________
> >>>Dynapi-Dev mailing list
> >>>[EMAIL PROTECTED]
> >>>http://www.mail-archive.com/[EMAIL PROTECTED]/
> >>>
> >>
> >>
> >>
> >>-------------------------------------------------------
> >>This SF.Net email is sponsored by the new InstallShield X.
> >>From Windows to Linux, servers to mobile, InstallShield X is the
> >>one installation-authoring solution that does it all. Learn more and
> >>evaluate today! http://www.installshield.com/Dev2Dev/0504
> >>_______________________________________________
> >>Dynapi-Dev mailing list
> >>[EMAIL PROTECTED]
> >>http://www.mail-archive.com/[EMAIL PROTECTED]/
> >>
> >
> >
> >
> >
> >
> >
> > -------------------------------------------------------
> > This SF.Net email is sponsored by the new InstallShield X.
> >>From Windows to Linux, servers to mobile, InstallShield X is the
> > one installation-authoring solution that does it all. Learn more and
> > evaluate today! http://www.installshield.com/Dev2Dev/0504
> > _______________________________________________
> > Dynapi-Dev mailing list
> > [EMAIL PROTECTED]
> > http://www.mail-archive.com/[EMAIL PROTECTED]/
> >
> >
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by the new InstallShield X.
> From Windows to Linux, servers to mobile, InstallShield X is the
> one installation-authoring solution that does it all. Learn more and
> evaluate today! http://www.installshield.com/Dev2Dev/0504
> _______________________________________________
> Dynapi-Dev mailing list
> [EMAIL PROTECTED]
> http://www.mail-archive.com/[EMAIL PROTECTED]/
>
>
-------------------------------------------------------
This SF.Net email is sponsored by the new InstallShield X.
>From Windows to Linux, servers to mobile, InstallShield X is the
one installation-authoring solution that does it all. Learn more and
evaluate today! http://www.installshield.com/Dev2Dev/0504
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/[EMAIL PROTECTED]/
