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
