hadoop-common-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sanjay Radia (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HADOOP-6668) Apply audience and stability annotations to classes in common
Date Mon, 10 May 2010 18:58:31 GMT

    [ 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.


Mime
View raw message