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 <[EMAIL PROTECTED]> 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: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
