XBean documentation (was Re: [ApacheDS] Big Bang Cleanup)

[Stefan Zoerner <st...@labeo.de>]

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.
> 
> http://cwiki.apache.org/confluence/display/DIRxPMGT/Demo-Docs
> 
> 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 
enabled.

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?

Re: XBean documentation (was Re: [ApacheDS] Big Bang Cleanup)

[David Jencks <da...@yahoo.com>]

On Sep 29, 2007, at 11:09 AM, Stefan Zoerner wrote:

> 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.
>> http://cwiki.apache.org/confluence/display/DIRxPMGT/Demo-Docs
>> 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 enabled.
>
> 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?
>
>
I think, as you suggest, that we should alter the javadoc until it  
produces a easy to understand and complete guide in the generated  
documentation.

If we run into limitations in the xbean plugin we can fix that too :-)

thanks
david jencks


>