directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <david_jen...@yahoo.com>
Subject Re: XBean documentation (was Re: [ApacheDS] Big Bang Cleanup)
Date Sat, 29 Sep 2007 19:32:10 GMT

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


>


Mime
View raw message