hadoop-common-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: (HADOOP-6668) Apply audience and stability annotations to classes in common
Date Mon, 10 May 2010 20:14:32 GMT

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

Doug Cutting commented on HADOOP-6668:
--------------------------------------

> if you really intend to make an interface audience-public please do so explicitly.

We need to make it clear to users what's stable and public: we don't want them to start using
something that's private or unstable without being well aware that they're doing so.  If an
API appears in Javadoc as 'public class Foo' with no further information then users might
assume that it will be supported in the future.  So if we choose to make 'private' or 'evolving'
the default for otherwise unmarked public classes, then we should remove such classes from
the Javadoc.

> from the point of view of the user of an interface - unless is it declared as audience-public
don't assume it is.

This is risky if they remain in the javadoc.  Folks are accustomed to assuming that documented
APIs without other qualifications are APIs that will be supported in the future.

If folks unwittingly use an evolving or private API and are broken by an upgrade it doesn't
help if we tell them they didn't read our fine print.  If we can get an "Evolving:" at the
front of the javadoc for every evolving feature (HADOOP-6675) and exclude all non-public APIs
from javadoc then users would be well forewarned.

We should use tools like JDiff to see what new APIs are introduced.  We should review the
list of new APIs in each release and check that those that we might not support long-term
are clearly marked as evolving.

I don't fundamentally care what the default is.  I do care what ends up in javadoc and in
releases.  Getting javadoc and jdiff to exclude classes without an explicit scope declaration
seems perhaps a lot of work when we'll still need to closely review what's in releases.  If
someone feels strongly that private or evolving should be the default then perhaps they should
work on getting javadoc and jdiff to enforce that?

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


Mime
View raw message