hadoop-mapreduce-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Doug Cutting (JIRA)" <j...@apache.org>
Subject [jira] Commented: (MAPREDUCE-1623) Apply audience and stability annotations to classes in mapred package
Date Wed, 28 Apr 2010 22:09:53 GMT

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


Mime
View raw message