Return-Path: 
 <dev-return-21707-apmail-directory-dev-archive=directory.apache.org@directory.apache.org>
Delivered-To: apmail-directory-dev-archive@www.apache.org
Received: (qmail 41318 invoked from network); 29 Sep 2007 18:08:19 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 29 Sep 2007 18:08:19 -0000
Received: (qmail 20148 invoked by uid 500); 29 Sep 2007 18:08:09 -0000
Delivered-To: apmail-directory-dev-archive@directory.apache.org
Received: (qmail 20110 invoked by uid 500); 29 Sep 2007 18:08:09 -0000
Mailing-List: contact dev-help@directory.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@directory.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@directory.apache.org>
List-Post: <mailto:dev@directory.apache.org>
List-Id: <dev.directory.apache.org>
Reply-To: "Apache Directory Developers List" <dev@directory.apache.org>
Delivered-To: mailing list dev@directory.apache.org
Received: (qmail 20099 invoked by uid 99); 29 Sep 2007 18:08:09 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 29 Sep 2007 11:08:09 -0700
X-ASF-Spam-Status: No, hits=1.2 required=10.0
	tests=SPF_NEUTRAL
X-Spam-Check-By: apache.org
Received-SPF: neutral (athena.apache.org: local policy)
Received: from [81.169.146.161] (HELO mo-p00-ob.rzone.de) (81.169.146.161)
    by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 29 Sep 2007 18:08:09 +0000
Received: from [127.0.0.1] (p548FD089.dip.t-dialin.net [84.143.208.137])
	by post.webmailer.de (klopstock mo20) (RZmta 13.2)
	with ESMTP id z00e3cj8TFrB7y for <dev@directory.apache.org>;
	Sat, 29 Sep 2007 20:07:46 +0200 (MEST)
	(envelope-from: <stefan@labeo.de>)
Message-ID: <46FE94C9.5060509@labeo.de>
Date: Sat, 29 Sep 2007 20:09:13 +0200
From: Stefan Zoerner <stefan@labeo.de>
User-Agent: Thunderbird 2.0.0.6 (Windows/20070728)
MIME-Version: 1.0
To: Apache Directory Developers List <dev@directory.apache.org>
Subject: XBean documentation (was Re: [ApacheDS] Big Bang Cleanup)
References: <a32f6b020709281519t465c961eoabfff6b80156c0c1@mail.gmail.com>
	 <DA3CBC71-389C-45A2-9DCC-A21C1C957609@yahoo.com>
	 <a32f6b020709281634q41b0c863qa891532359df6858@mail.gmail.com>
 <d45b08f00709290334i3f1cb5l74c5aa3b28fecfb0@mail.gmail.com>
 <46FE2D52.1080109@apache.org>
 <5EBACE38-F8B4-4207-9812-CF76070F65AF@yahoo.com>
 <46FE7E39.7040402@apache.org>
In-Reply-To: <46FE7E39.7040402@apache.org>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-RZG-AUTH: kR2YrGeU3i5GJZNxbYfAbITnBeX/YWiFZ/RSZNN7D9RkvGeI3+yfe8Qcgw==
X-RZG-CLASS-ID: mo00
X-Virus-Checked: Checked by ClamAV on apache.org

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?