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