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.

View raw message