You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Apache Wiki <wi...@apache.org> on 2008/01/27 18:05:06 UTC
[Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
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
Re: [Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
Posted by sebb <se...@gmail.com>.
On 27/01/2008, Roland Weber <os...@dubioso.net> wrote:
> sebb wrote:
> > 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?
>
> Makes sense, though I believe these are not JavaDocs?
> I have to read up on this stuff one of these days.
> (so much to do on that "one of these days"...)
>
Yes, sorry - I should have made it clear that this is a follow-on from
the details in the Wiki.
It looks like at least some of the annotations appear in the Javadoc -
e.g. ThreadSafe does.
> > For 1.4 and earlier, maybe they could be included as comments?
> >
> > The @GuardedBy annotation is potentially very useful.
>
> I don't mind making the JavaDocs more useful, if that is
> what you mean with "as comments". I wouldn't see a point in
> comments only visible in the source, like /*@ThreadSafe*/.
>
Well, the annotations are more useful if they appear in Javadoc, but
they still have use in comments. E.g. @GuardedBy would be useful to
developers, and even ThreadSafe would be useful as a reminder not to
compromise the code.
As soon as the code needs 1.5, the comment markers could be removed.
> cheers,
> Roland
>
> ---------------------------------------------------------------------
> 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
Re: [Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
Posted by Roland Weber <os...@dubioso.net>.
sebb wrote:
> 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?
Makes sense, though I believe these are not JavaDocs?
I have to read up on this stuff one of these days.
(so much to do on that "one of these days"...)
> For 1.4 and earlier, maybe they could be included as comments?
>
> The @GuardedBy annotation is potentially very useful.
I don't mind making the JavaDocs more useful, if that is
what you mean with "as comments". I wouldn't see a point in
comments only visible in the source, like /*@ThreadSafe*/.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: [Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
Posted by sebb <se...@gmail.com>.
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 <wi...@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