Hi, I'm not familiar at all with the Ant project, but I am familiar with Apache by itself, for most common things. I'm not a huge fan of Java at all, nor am I fan of using one language for everything, but I am a fan of having everything in as many languages as possible, and to that degree, have no objection to Java, but think it's a good idea. To me, that is true "portability" of a high-level package, to run in any high-level language, which has interpreters or compilers for every platform. Some may cry "maintenance nightmare", but it doesn't phase me.
About Perl, it uses something called POD (Plain Old Documentation), which is an extremely simplistic syntax which can exist simultaneously with Perl code in the same file. The Perl interpreter or compiler ignore POD, and POD ignores Perl code. There are converters such as pod2man and pod2html (and a few other formats) which extract and format the POD from the source file. However, there is no template. It is hard-coded into pod2man and pod2html (etc.), and basically only creates a simplistic UNIX man page or HTMLized man page. One would have to create a parser that either reinvents the (POD) wheel entirely, implementing a template system and introducing more hooks for fields and custom formatting, or create a parser that can parse the stock HTML output, but require that the coder leave comments formatted very carefully so that they can be post-processed. The first is a cleaner solution, but involves more work, and duplicates some functionality that already exists, and will no longer be tied to the stock POD parser, so any changes to the stock POD parser or syntax would have to be duplicated, which incurs a slight maintenance fee, or else lock the POD syntax we use and require coders to use a potentially older syntax. The second solution may break at any time if the behaviour of the stock POD parser changes, but might be quicker to implement at first, and might not be subjected to the same maintenance fee, but things could still break if the POD parser changed, regardless of the same syntax freeze. With that said, it's not really expected that POD changes too much or anything anyways. ;-) And this is just to cover the JavaScript and Perl code. I think for a project like ours with multiple languages, it would be desireable to have a universal comment parsing engine, which can use the same templates, so that all documents generated look more or less the same. Plugins would be used for extracting the actual comments, with fields labelled to act as special hooks for formatting and organizing information about variables, functions, objects, etc.. I do not think a strict JavaDoc style would suit every language. Each language has their own quirks. Trying to make comments from a C program look like they're object oriented probably wouldn't work too well. Perl has some things it calls packages, which may or may not also be objects, which again, may or may not also be classes, depending on how it is coded and what version of Perl is in use. Furthermore, some code which uses the package, may also be using plain functions, object method calls, or fully fledged class calls, depending on the syntax used in both the package and the calling script. Perl also has no such thing as a private, public, or protected variableor method calls in object oriented programming (design philosophy: "Stay out of my living room, not because I have a shotgun, but because you weren't invited.", it's up to the users of an object not to go poking around where they do not belong, using intentionally undocumented internal variables, which allows the object programmer to document an interface, yet change the internals at will.). That's not to say that variables can't be protected very well by the programmer (at a slight performance cost) using such a thing as a "closure" in Perl. But detecting if code contains a closure, and then calling it "protected" or "private", and similar detections, would be too much for a comment parser to try and determine all of this based on code interpretation. Then the effort to analyze the source would be greater than the output of documentation, and would probably be very error prone. That said, I have nothing against the JavaDoc format. For Java, I think it's excellent. The Perl POD is lackluster by comparison. There may already be Perl modules addressing all these issues in CPAN, so it may not be as hard as I imagine to get POD comments from a Perl source, and generate JavaDoc-like documentation. I will research when I have the time. Quite busy at the moment, with some oldie upgrades and vintage overclocking. (From 486 to Socket 7 to Super 7 to Slot A to Socket A, my first 5 mainboards). Catching up on 7 years of upgrades and overclocking in a week has been insane. Getting all the research done and obtaining the vintage parts has been maddening. Getting things working and doing stability and performance tests and taking measurements for empirical data is going to be interesting. Trying out the 3-dozen mostly undocumented DIP settings for an old PNY Quickchip, and stabalizing and benchmarking each working setting is going to be gruelling. Documenting all my research should prove challenging; I'll have to make archives of literally dozens if not hundreds of web pages and images, since they always seem to have gone down when you go looking for them in a year (links to original sites incase they are still alive, or still maintained too). The results, will be put on a personal web site and hopefully be enlightening for someone stupid enough (erm) to undertake some old upgrades. Leif ----- Original Message ----- From: "Rob Butler" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Thursday, June 10, 2004 8:52 AM Subject: Re: [Dynapi-Dev] Suggestions > 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 ove > r 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]/
