Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@apache.org Received: (qmail 79827 invoked from network); 19 Nov 2002 22:35:50 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 19 Nov 2002 22:35:50 -0000 Received: (qmail 18091 invoked by uid 97); 19 Nov 2002 22:36:37 -0000 Delivered-To: qmlist-jakarta-archive-commons-dev@jakarta.apache.org Received: (qmail 17989 invoked by uid 97); 19 Nov 2002 22:36:36 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 17947 invoked by uid 98); 19 Nov 2002 22:36:35 -0000 X-Antivirus: nagoya (v4218 created Aug 14 2002) Message-ID: <3DDABCB0.5080505@mdh.se> Date: Tue, 19 Nov 2002 23:35:28 +0100 From: Fredrik Westermarck User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.1) Gecko/20020826 X-Accept-Language: sv, en MIME-Version: 1.0 To: Jakarta Commons Developers List Subject: Javdoc formatting (Was: [lang] [patch] Javadoc improvements) References: Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Scanned: by AMaViS-perl11-milter (http://amavis.org/) X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N Henri Yandell wrote: > I'm all for having consistent javadoc. Feel like writing up the 'rules' > for the javadoc style you've ended up on? Hi! Here is the promised rules that I try to follow when writing javadoc. Ofcourse the Sun javadoc guidelines is used, this is only to be seen as an extension of them to make it easier for users reading the generated docs and developers with javadoc-popup capabilities from within their IDE. General: References to other objects, interfaces or methods use the @link-tag the first time it is referenced in a class or interface. On the following references always enclose it inside . Classes/Interfaces/Methods: Use a short description of what the class/interface/metod is used for, enclose with

. A longer description about what the class/interface/metod is used for and if it is needed how it is done. If it is nessesary include description of the parameters, what they are used for and how. Enclose with

where it is needed, try to divide into smaller parts (not to small!) to enhance readability of the generated Javadoc. If an example is needed enclose it with

. If an example was given write an explanation of the example within

. -- To unsubscribe, e-mail: For additional commands, e-mail: