[
https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12865866#action_12865866
]
Sanjay Radia commented on HADOOP-6668:
--------------------------------------
>> > * If an API is not annotated
>> ... It should default to audience-private unstable.
>I don't agree with this since it violates the principle of least surprise - if
>an otherwise unannotated class is public, then a user would reasonably expect
>it to be public.
Making an interface public is a big deal - it is basically a contract to
support that interface in a compatible fashion for a very long time.
Hence if you really intend to make an interface audience-public please do so
*explicitly*.
Most language default a non-declared field or method to be private. Ours is the
same.
I don't understand your point of principle of least surprise. From the point
of view of the provider of the interface, there is no surprise - unless it is
declared explicitly as audience-public it is not. Similarly, from the point of
view of the user of an interface - unless is it declared as audience-public
don't assume it is.
It is unfortunate that Java does not have sub-package private -this would have
allowed us to significantly reduce the number of public elements.
Thus we need to explicitly label every interface that is audience-public
(regardless of stability), and all audience-private interfaces that are stable,
or evolving.
Labeling everything is not necessary; further it is not possible to
maintainthis consistently over time. Will we reject every patch that had
undeclared classification?
Our record for enforcing Javadoc is pathetic.
> Apply audience and stability annotations to classes in common
> -------------------------------------------------------------
>
> Key: HADOOP-6668
> URL: https://issues.apache.org/jira/browse/HADOOP-6668
> Project: Hadoop Common
> Issue Type: Sub-task
> Components: documentation
> Reporter: Tom White
> Assignee: Tom White
> Priority: Blocker
> Fix For: 0.21.0
>
> Attachments: common.interface-tw-annotated.txt, HADOOP-6668.patch,
> HADOOP-6668.patch, HADOOP-6668.patch, HADOOP-6668.patch, HADOOP-6668.patch,
> HADOOP-6668.patch
>
>
> Mark private implementation classes with the InterfaceAudience.Private or
> InterfaceAudience.LimitedPrivate annotation to exclude them from user Javadoc
> and JDiff.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
