[Helma-user] New helmadoc/jsdoc based reference

[Chris Zumbrunn]

On Feb 18, 2007, at 23:37 , <tobias.schaefer at orf.at> wrote:

> hi chris
>
> this is a very nice effort with a great output.
>
> i am glad to see my suggestion being adapted so well.
>
> btw. what is the reason for trying to remain compatible with
> jsdoc, helmadoc and scriptdoc?
>
> wouldn't it be better to decide for one (or max. two) of them?

Maybe it will be, yes. I think it depends on how easy/problematic  
support for all three will be.

The advantage of JSDoc support is that it currently offers the best  
control over the way static docs are rendered. The fact that it is  
perl is a downside in my opinion, as javascript or java would be  
better in the context of Helma. Also, it behaves a bit erratic at  
times and decides not to like certain source files, causing it to seg- 
fault during rendering attempts. Sometimes just adding or removing  
some random whitespace in a certain section of the file can make the  
difference whether JSDoc chokes on the file or not.

The advantage of helmadoc support of course is that it works with the  
built-in API rendering, offering the ability to generate auto- 
updating docs together with the apps that are being developed.  
Generally, the big benefit of helmadoc is that it can be smart about  
Helma specific coding conventions.

Currently, the only advantages of scriptdoc that I can see are the  
better code completion and inline documentation for those of us using  
Aptana as their editor of choice.

> and as you mention jsdoc2; what's the current state of that
> very version?

The good news about JSDoc2 is that it is written in javascript, not  
perl anymore. Since November, the status has been that the code  
parser was already implemented and the main part that was still  
missing was the template mechanism to actually output the  
documentation in a meaningful way. I see Michael Mathews just  
committed template related additions a few hours ago. So, JSDoc2  
might just have become a lot more intersting overnight.

http://jsdoc-2.googlecode.com/svn/

The downside of JSDoc2 is that it relies entirely on the javadoc  
style comments and basically ignores the actual code entirely. This  
is a downside if we are looking at JSDoc2 as a possible replacement  
for helmadoc, in the sense that the documentation it generates will  
not reflect the actual application's code, but it's state of  
documentation. However, special Helma coding conventions could maybe  
still be reflected in JSDoc2 generated documentation as a result of  
specially designed templates. Basically, any Helma specific magic  
would need to happen during rendering instead of during the parsing,  
which actually might be easier and more flexible. So, this maybe  
isn't really a downside at all.

Cheers,
Chris

> thanks, and keep up the good work.
>
> ciao,
> tobi
>
>
> -----Original Message-----
> From: helma-user-bounces at helma.org on behalf of Chris Zumbrunn
> Sent: Sun 18-Feb-07 20:25
> To: Helma User Mailing List
> Subject: [Helma-user] New helmadoc/jsdoc based reference
>
> Hi there,
>
> In order to share the current state of the ongoing documentation
> effort, I uploaded several renderings of what I've been experimenting
> with. Hopefully, the core reference is now pretty much completely
> documented. If you notice mistakes or any hidden jewels that are
> still missing, please let me know. The same goes for things you think
> should be deprecated and that aren't marked as such.
>
> All the built-in properties and methods are now documented using
> javadoc style comments in "artificial" code files:
>
> http://helma.zumbrunn.net/reference/source/
>
> These files are checked into the CVS repository as "reference" in the
> apps module:
>
> http://adele.helma.org/source/viewcvs.cgi/reference/
>
> If this reference is included in an application as a repository, the
> "artificial" code lives inside the core* prefixed prototypes and
> would not effect a running application. This makes it possible to
> include the reference as a repository during development in order to
> see the documentation for the built-in methods and properties
> together with the documentation for the application that is being
> developed, when accessing the helmadoc generated documentation
> through the showAPI and renderAPI links in the manage application. An
> example of how this currently looks like, using the welcome app as a
> guinea pig, can be seen here:
>
> http://helma.zumbrunn.net/reference/helmadoc/
>
> Of course, having javadoc formatted source files for our reference
> also opens up all kinds of other posibilities, such as using JSDoc to
> render the documentation or using the files as libraries for code
> completion and inline documentation in Aptana. Here is an example of
> a rendering using JSDoc:
>
> http://helma.zumbrunn.net/reference/jsdoc/
>
> The advantage of this approach is that it looks very much like what
> we are all used to from standard javadoc generated documentation, for
> example the docs for Helma's Java API:
>
> http://helma.zumbrunn.net/reference/javadoc/
>
> Using JSDoc, I also experimented with templates that would adjust the
> look & feel to integrate with the current Helma website. Here are
> three different renderings, one for only the built-in core
> functionality, one for the core + helmaLib and one for the core +
> helmaLib + the new jala lib:
>
> http://helma.zumbrunn.net/reference/core/
> http://helma.zumbrunn.net/reference/corelib/
> http://helma.zumbrunn.net/reference/combined/
>
> The general idea in all this is to come up with a way of formatting
> the files in a way that will work reasonably well for as many
> different use cases as possible, including helmadoc, JSDoc, JSDoc2
> and scriptdoc. Targeting all these different tools is a bit of a
> compromise, which can cause some minor problems in any of the three
> environments currently.
>
> Any critic, suggestions or other feedback will be very much  
> appreciated.
>
> Cheers,
> Chris
>
> _______________________________________________
> Helma-user mailing list
> Helma-user at helma.org
> http://helma.org/mailman/listinfo/helma-user
>
> <winmail.dat>
> _______________________________________________
> Helma-user mailing list
> Helma-user at helma.org
> http://helma.org/mailman/listinfo/helma-user