[jira] Commented: (HADOOP-6668) Apply audience and stability annotations to classes in common

["Sanjay Radia (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12863950#action_12863950 ] 

Sanjay Radia commented on HADOOP-6668:
--------------------------------------


The propsoal in HADOOP-5073 and HADOOP-6289 have used different criteria than
the one stated in this Jira (see TW's comment in the begining of this Jira)
Let me clarify:
> * Public user APIs should be marked as 'public stable'. These appear in public Javadoc.
> * APIs that are exposed to the user but not coded against directly should be marked as 'public evolving'. ... 
> These appear in public Javadoc.

Java public does *not* imply audience public. An interface is audience public only if we expect applications to use it directly. This is probably the biggest difference between the approach taken in this jira and HADOOP-6289.
I do not fully understand the distinction you are trying to make in " APIs that are exposed to the user but not coded against directly  (e.g. the metrics API,)" 
I disagree with your metrics example: we should not expose APIs like metrics as audience public. They should be limited private. 
Don't mark an interface  audience-public unless it is absolutely necessary.
 
> * Non-user facing APIs that are used within HADOOP subprojects should be marked as 'limited-private evolving' 
> (e.g. RPC) or 'limited-private unstable'. These appear in developer Javadoc.
In the majority cases I agree, except that 
some private  interfaces need to be marked as  stable: protocols like client protocol should be marked as
limited-private and *stable*. They impact  interoperation and in the future they will impact rolling upgrades.
Again see the HADOOP-5073's FAQ.

> * Anything that is private implementation code should be marked as 'private unstable'. These appear in developer Javadoc.
Agreed.

> * If an API is not annotated then it defaults to the usual Java visibility and Apache HADOOP stability (http://wiki.apache.org/hadoop/Roadmap) rules.
This is different than what was stated in HADOOP-5073. It should default to audience-private unstable.

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