[Helma-user] New helmadoc/jsdoc based reference

[Chris Zumbrunn]

On Feb 19, 2007, at 11:08 , Robert Gaggl wrote:

> hi chris,
>
> that looks great!
>
>> 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.
>
> just some quick findings: in req the documentation of get() and
> getMethod() is missing (i guess that's because of weird jsdoc
> behaviour).

They just are currently not documented. In all the cases of getter/ 
setter javabean properties, I'm not sure what we want to document.  
For example, I apparently at one point had getMethod documented, then  
switched to documenting the method property instead (and left some  
references to the getMethod method in @see tags elsewhere). Should we  
always document both ways of accessing javabean getters and setters?  
I don't think that's practical. But then when should which version be  
documented? Any suggestions for a good rule of thumb?

In the case of req.get() I probably thought it was duplicative of  
req.data, which it is, but I think suppressing it in the docs because  
of that was a mistake.

> and the return type of getServletRequest() is prefixed with
> "Packages.", shouldn't that be unprefixed?

My thinking was that it's best to always prefix any references to  
java classes with the Packages prefix, just for consistency, even if  
it is not necessary. In the case of  
javax.servlet.http.HttpServletRequest we anyway definitely need the  
prefix, since javax is not directly accessible like the java  
namespace would be.

Chris