[
https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Tom White updated HADOOP-6668:
------------------------------
Attachment: HADOOP-6668.patch
I have had a first attempt at applying annotations to the common codebase. They
are summarized in this table; consult the patch for finer-grained detail.
||Package org.apache.hadoop.|| Visibility & Stability || Notes ||
|classification|public stable| Should we mark them evolving?|
|conf|public stable| |
|fs|public stable|filesystem implementations are public stable, but any
internal classes are private unstable|
|fs.shell|private unstable| |
|http|limited-private unstable| |
|io|public stable| |
|io.compress|public stable| |
|io.compress.bzip2|private unstable| |
|io.compress.zlib|private unstable| |
|io.file.tfile|public evolving| |
|io.retry|limited-private evolving| |
|io.serializer*|public evolving| |
|ipc*|limited-private evolving| |
|metrics*|public evolving| |
|net|mixture of public evolving and limited-private unstable| |
|record*|deprecated| |
|security*|mixture of public/limited-private evolving?| |
|util|public evolving|GenericOptionsParser, ReflectionUtils, Progressable,
Tool, ToolRunner are public stable|
|util.bloom|public stable| |
|util.hash|public stable| |
I haven't annotated the security APIs yet - if anyone has suggestions for
these, I'd be grateful.
I'm wondering whether to mark deprecated elements as 'evolving' (if they were
deprecated in 0.19 or earlier), so that they can be removed sooner than the
next major release. We wouldn't necessarily do this, but it might be wise to
have the option.
Here are some guidelines that I used in applying the annotations. Selecting the
annotations to apply is a judgement call, so I'd appreciate feedback both on
the general rules and the particular annotations I have applied.
* 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' (e.g. the metrics API, which is used in
configuration). These appear in public Javadoc.
* 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.
* Anything that is private implementation code should be marked as 'private
unstable'. These appear in developer Javadoc.
* 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.
> 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: Improvement
> Components: documentation
> Reporter: Tom White
> Assignee: Tom White
> Attachments: 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.
