hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
Date Sun, 27 Jan 2008 17:12:34 GMT
For Java 1.5 and up, one can use Annotations such as:

@ThreadSafe
@NotThreadSafe
@GuardedBy
@Immutable

Perhaps it would be a good idea to start including these where possible?

For 1.4 and earlier, maybe they could be included as comments?

The @GuardedBy annotation is potentially very useful.

On 27/01/2008, Apache Wiki <wikidiffs@apache.org> wrote:
> Dear Wiki user,
>
> You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change
notification.
>
> The following page has been changed by RolandWeber:
> http://wiki.apache.org/HttpComponents/JavaDocGuidelines
>
> The comment on the change is:
> moved from old wiki
>
> New page:
> = HttpComponents JavaDoc guidelines =
>
> == Interface description must consist of ==
>  * Purpose
>  * Description (''optional'')
>  * Statement whether this interface represents an entity or a process defined by a standard
specification such as RFC document, when applicable (''optional'')
>
> == Class description must consist of ==
>  * Purpose
>  * Description (''optional'')
>  * Statement whether this class implements an entity or a process defined by a standard
specification such as RFC document, when applicable (''optional'')
>  * Statement whether instances of this class are mutable (''optional''). If not explicitly
stated, instances of this class are assumed to be mutable
>  * Statement whether this class is multi-threading safe (''optional''). If not explicitly
stated, the class is assumed to be '''NOT''' threading-safe
>
> == Method description must consist of ==
>  * Purpose
>  * Expected effect
>  * Description (''optional'')
>  * Statement whether this method is modal, that is, if the object must be in a specific
state (pre-conditions) or mode in order to execute correctly (''optional''). If not explicitly
stated, the method is assumed to be non-modal.
>  * Required parameters. It must be explicitly stated whether null is permitted as a parameter
value. Per default parameters are assumed to require a non-null value and to cause a {{{ IllegalArgumentException
}}} if null is given.
>  * Exceptions that can be thrown in the course of method's execution and their possible
cause (post-conditions).
>  * private methods can have minimal or no !JavaDocs if they are short and trivial enough.
>  * methods that implement a signature from an interface or base class that is sufficiently
documented there can omit !JavaDocs in favor of comments like:
>
>  {{{ // non-javadoc, see interface XXX }}}
>
>  {{{ // non-javadoc, see class XYZ }}}
>
>  The non-javadoc comment with a pointer to the documentation is required for people reading
the source code. The !JavaDoc tool will automatically copy the description from the interface
or base class into the generated documentation.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org


Mime
View raw message