directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Zoerner <>
Subject XBean documentation (was Re: [ApacheDS] Big Bang Cleanup)
Date Sat, 29 Sep 2007 18:09:13 GMT
Stefan Zoerner wrote:
> I have tried whether Confluence is able to render it, and it is 
> (although there is HTML embedded in it).
> My first impression:
> We will probably have some process to re-organize the content a bit, but 
>  it looks like a very good point to start.
> But I will need some more time to figure it out. Thanks for the hint, 
> David!

It seems that the javadoc from the getters is the source for the 
generated XBean documentation.

In this case I would like to optimize the javadoc content in order to 
get it right for the generated configuration docs.

For instance we have this in class StartupConfiguration:

      * Returns <tt>true</tt> if access control checks are enabled.
     public boolean isAccessControlEnabled()
         return accessControlEnabled;

This leads in the table to a line

accessControlEnabled|boolean|Returns true if access control checks are 

which is nice except of the "Returns", because if someone (e.g. an 
admin) who plans to configure the server reads this, the "returns" may 
confuse him/her.

I would therefore suggest to simply write

      * true, if access control checks are enabled.

or even better

      * true, if access control checks are enabled (default is true).

If we add the default value here (if any), we do not have to add it by 
hand in the docs, which would really be nice ...

What do you think?

View raw message