Javadoc for default methods of an interface

[Behrooz N]

Hi,

I was wondering if there is a way to specify the "default" value returned
by a defender method of an interface that would be processed specifically
by javadoc of Java 8? And, how fair this expectation is or what is the
argument not to have it?

Thanks in advance,
Behrooz

[Brian Goetz]

There are some new javadoc tags to let you separate normative from
non-normative, and how it applies separately to the interface vs the
default implementation. They are:

@implSpec -- *specification* about what the default implementation does,
such as "the default implementation throws UOE". This can be counted on
by subclasses to make decisions about "should I override this or not".

@implNote -- non-normative notes about the implementation, which
historically have been prefaced by "implementation note".

@apiNote -- non-normative notes about the API, such as examples of how
to use it.

The fourth quadrant, normative spec about the interface, needs no tag
since that's what the spec is for.

Post by Behrooz N
Hi,
I was wondering if there is a way to specify the "default" value returned
by a defender method of an interface that would be processed specifically
by javadoc of Java 8? And, how fair this expectation is or what is the
argument not to have it?
Thanks in advance,
Behrooz

[Mike Duigou]

The new tags are used in JDK docs but aren't standard javadoc tags. It's necessary to use the -tag option to define them so that javadoc tool will recognize then in source outside the JDK.

@implSpec -- *specification* about what the default implementation does, such as "the default implementation throws UOE". This can be counted on by subclasses to make decisions about "should I override this or not".
@implNote -- non-normative notes about the implementation, which historically have been prefaced by "implementation note".
@apiNote -- non-normative notes about the API, such as examples of how to use it.
The fourth quadrant, normative spec about the interface, needs no tag since that's what the spec is for.

Post by Behrooz N
Hi,
I was wondering if there is a way to specify the "default" value returned
by a defender method of an interface that would be processed specifically
by javadoc of Java 8? And, how fair this expectation is or what is the
argument not to have it?
Thanks in advance,
Behrooz

[Behrooz N]

Thanks for your examples and explanations.

Post by Mike Duigou
The new tags are used in JDK docs but aren't standard javadoc tags. It's
necessary to use the -tag option to define them so that javadoc tool will
recognize then in source outside the JDK.

Post by Brian Goetz
There are some new javadoc tags to let you separate normative from

non-normative, and how it applies separately to the interface vs the

Post by Brian Goetz
@implSpec -- *specification* about what the default implementation does,

such as "the default implementation throws UOE". This can be counted on by
subclasses to make decisions about "should I override this or not".

Post by Brian Goetz
@implNote -- non-normative notes about the implementation, which

historically have been prefaced by "implementation note".

Post by Brian Goetz
@apiNote -- non-normative notes about the API, such as examples of how

to use it.

Post by Brian Goetz
The fourth quadrant, normative spec about the interface, needs no tag

since that's what the spec is for.

Post by Brian Goetz

Post by Behrooz N
Hi,
I was wondering if there is a way to specify the "default" value

returned

Post by Brian Goetz

Post by Behrooz N
by a defender method of an interface that would be processed

specifically

Post by Brian Goetz

Post by Behrooz N
by javadoc of Java 8? And, how fair this expectation is or what is the
argument not to have it?
Thanks in advance,
Behrooz