Javadoc conventions in the presence of default methods

[Brian Goetz]

> I agree that the different parts should be separately inheritable.  If a
> subtype overrides a method though, I think only the main doc should be
> inherited (since the implspec parts seem to be mainly for the benefit of
> implementers, and afaict you cannot override a default method without
> changing or dropping its implementation).

OK good, since that's how it was proposed.

> I'm not sure I'm really keen on separating specification from notes
> though.  That seems pretty specific to organizational preferences and
> conventions.  It seems to me that you'd want to inherit API notes along
> with API spec always, and you'd want to keep implementation notes with
> the implementation spec always, thus it just becomes a formatting
> nicety.  Put another way, we've gone this long without; why do we
> suddenly need it now?

It is not like the "need it" function has gone precipitously from zero 
to one.  Realistically, its been creeping up slowly for years, and API 
maintainers have to go through all sorts of hoop-jumping to specify 
things, and there has been much effort spent fixing spec bugs (or worse, 
living with bad spec) that amount to conflating normative/informative or 
api/implementation spec.

Adding default methods will increase the need in a nontrivial way. 
Until recently, there were only a few examples of optional methods in 
the JDK, mostly the mutative methods in Abstract{Collection,List,Map}. 
So there were a few of them, we could get by with a crutch.  But as 
we'll be getting more, the crutches don't scale.  People constantly make 
mistakes with the use of phrases like "this implementation" where its 
not clear what that actually means.

So, its been a problem all along, been getting slowly worse with age, 
and we're about to dump some gas on an already-burning fire.