@FunctionalInterface and Javadoc

[Paul Benedict]

I tried out several messages -- looking at them seeing what kind of
reaction I would have as a new user.

At first, I just said "This interface is an implicit functional interface"
but it begs the question why it's implicit and not explicit. We all know
the answer why, but I don't think it's easily apparent.

Second, I specifically did not say it "is" a functional interface because I
didn't want to give the impression it was intended to be. I went for
something that made it sound coincidental: "This interface matches the
requirements for a functional interface." However, I am left with the same
question: why isn't it just a functional interface? Why all the
qualifications?

I also don't like how a full understanding may require a bunch of
qualifications/warnings: use at your own risk, interface may evolve,
missing @FunctionalInterface by designer, etc.

I come to the conclusion that it's better not to document the implicitness.
If people want to use a functional interface, they should just a "true" one
marked as @FunctionalInterface. Let them figure out the implictness on
their own.

Paul



On Mon, Nov 25, 2013 at 6:53 PM, David Holmes <david.holmes at oracle.com>wrote:

> On 26/11/2013 10:41 AM, Brian Goetz wrote:
>
>> 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.
>>
>
> I would think you still want both as discussed in the email thread, but
> with different wording, also as discussed. I can imagine existing libraries
> being used across 7 and 8 and so not being able to apply @FI.
>
> I think something like:
>
> "In its current form this is implicitly a functional interface."
>
> which captures the implicit-ness and that in the future, should the
> interface be enhanced, it may no longer be a functional interface.
>
> David
>



-- 
Cheers,
Paul