@FunctionalInterface and Javadoc

[Brian Goetz]

A long time ago, we agreed that the Javadoc for a functional interface 
should say something like "This is a functional interface."  This is 
done using a structural analysis of the interface, just as when used as 
the target of a lambda.

Later in time, we arrived at @FunctionalInterface, which is optional to 
use.  It is closest in spirit to @Override, since:
  - It captures design intent
  - It enlists the compiler's aid in catching violations of such intent; 
an @FI-marked method that is not a functional interface will merit a 
compile error.

It has recently been pointed out that perhaps we should adjust the 
Javadoc generation, to trigger off of @FI rather than structurally, 
since there are functional interfaces in the JDK that are not marked @FI 
(deliberately) but which still bear the "This is a functional interface" 
blurb.