[
https://issues.apache.org/jira/browse/MAPREDUCE-1623?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12861962#action_12861962
]
Doug Cutting commented on MAPREDUCE-1623:
-----------------------------------------
> The warnings in javadoc are redundant with the annotations [ ... ]
Indeed, but annotations are not very prominent. The "evolving" status should
be nearly as prominent as "deprecated": we want folks to be aware when they use
an evolving API that their application might break when they upgrade Hadoop.
We don't want folks to be surprised by this or else we'll be dealing with upset
users. Deprecations, by adding something to the first javadoc sentence, are
visible in the package and method summary tables, while the annotations are
visible in the detailed javadoc, and even then in a smaller typeface so they
are easily missed. We might skip the bold that's used for deprecation, but
adding something to the first sentence for evolving methods and classes will go
a long way towards reducing upgrade surprises.
> Apply audience and stability annotations to classes in mapred package
> ---------------------------------------------------------------------
>
> Key: MAPREDUCE-1623
> URL: https://issues.apache.org/jira/browse/MAPREDUCE-1623
> Project: Hadoop Map/Reduce
> Issue Type: Sub-task
> Components: documentation
> Reporter: Tom White
> Assignee: Tom White
> Priority: Blocker
> Fix For: 0.22.0
>
> Attachments: M1623-1.patch, MAPREDUCE-1623.patch,
> MAPREDUCE-1623.patch, MAPREDUCE-1623.patch, MAPREDUCE-1623.patch,
> MAPREDUCE-1623.patch, MAPREDUCE-1623.patch, MAPREDUCE-1623.patch
>
>
> There are lots of implementation classes in org.apache.hadoop.mapred which
> makes it difficult to see the user-level MapReduce API classes in the
> Javadoc. (See
> http://hadoop.apache.org/common/docs/r0.20.2/api/org/apache/hadoop/mapred/package-summary.html
> for example.) By marking these implementation classes with the
> InterfaceAudience.Private annotation we can exclude them from user Javadoc
> (using HADOOP-6658).
> Later work will move the implementation classes into o.a.h.mapreduce.server
> and related packages (see MAPREDUCE-561), but applying the annotations is a
> good first step.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
