[
https://issues.apache.org/jira/browse/HADOOP-5073?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12699977#action_12699977
]
Jakob Homan commented on HADOOP-5073:
-------------------------------------
Had an offline talk with Sanjay and went over these issues.
One item that came up was the terminology. Scope may be a confusing term to
use as it overloads a standard comp. sci term and may not be clear to new
people approach our use of it. Since the goal of the scope classification is
to indicate who should use the class, would audience be a more appropriate
choice? Similarly with stability, it would probably be good to always refer to
that as APIStability, lest our code gets tagged with "Unstable" all over and
frightens away anyone looking it over to consider using Hadoop in production.
Without proper context, stability and scope may not convey the appropriate
meanings.
I've been playing around with using annotations approach and in general they
work nicely. Annotations such as (rough versions without proper documentation):
{code}package annotations;
import java.lang.annotation.Documented;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Documented
@Retention(RetentionPolicy.CLASS)
@Inherited
public @interface Audience {
public enum AUDIENCE {
/**
* the interface is for general use by any application.
*/
Public,
/**
* the interface is used by a specified set of projects or systems (typically
closely related projects).
*/
LimitedPrivate,
/**
* Only for use within application, not for use by general developers
*/
ProjectPrivate }
AUDIENCE value();
}{code}
and
{code}package annotations;
import java.lang.annotation.Documented;
import java.lang.annotation.Inherited;
@Inherited
@Documented
public @interface APIStability {
public enum Stability { Stable, Evolving, Unstable };
Stability value();
}{code}
allows for reasonable, very clear documentation of code:
{code}package eccleston;
import static annotations.Audience.AUDIENCE.Public;
import annotations.APIStability;
import static annotations.APIStability.Stability.Evolving;
import static annotations.APIStability.Stability.Stable;
import annotations.Audience;
/**
* Time and Relative Dimensions in Space
*/
@Audience(Public)
@APIStability(Stable)
public class TARDIS {
public void materialize() { System.out.println("whoop! WHOop! WHOOP!"); }
public void dematerialize() { System.out.println("WHOOP! WHOop! whoop!"); }
@APIStability(Evolving) // We can mark individual methods as necessary
public void blendIn() { System.out.println("Now I'm a police box! That'll
work."); }
}{code}
By using the @Documented meta-annotation, the audience and api-stability
annotation appear in the javadoc. This is good:
{noformat}
eccleston
Class Tardis
java.lang.Object
eccleston.TARDIS
Direct Known Subclasses:
Type2TARDIS
@Audience(value=Public)
@APIStability(value=Stable)
public class TARDIS
extends java.lang.Object
Time and Relative Dimensions in Space
{noformat}
Unfortunately, there are two issues:
* Even though it's @Documented and @Inherited, the documentation doesn't get
inherited, so even though subclasses of this type *do* have the @APIStability
annotation (you can query for it using reflection), it doesn't show up in their
javadoc. This makes it difficult to just mark a class as such-and-such
stability or audience and assume that takes care of it down the line. This
really seems wrong; certainly not the behavior I expected. I played with
writing a doclet to do something like this, but the doclet interface is rather
cheesy and doesn't allow you to modify the code information, just read it.
* Eclipse doesn't seem to show the annotations in its javadoc view, which makes
it more difficult for coders who rely on these facilities for first-line
identification of code and classes they should and shouldn't use.
I had hoped we could just use package-info.java to mark a class' audience and
api-stability and have it propagate all the way down the line in the
documentation, but that doesn't work. In addition to issue one above, the
@Inherited meta-annotation can only be applied to classes. As a partial remedy
to these issues, we could write a documentation tool to check if new code is
using any unstable/private apis and emit a warning, as part of test-patch or
such.
Taglets show up in the javadoc quite boldly, but I can't find a way to
propagate them; we'd have to explicitly mark each section we wanted to tag (or
write a tool to do it).
Since we can't just mark a top level class and have it show up all down the
line, having default values may not be a good idea after all. It's probably
best to explicitly set the audience/api-stability value when the annotation is
applied.
So, the annotation approach may work but it's not as in-your-face as I was
hoping for helping coders to immediately see which resources they should or
shouldn't use in their development environments.
> Hadoop 1.0 Interface Classification - scope (visibility - public/private) and
> stability
> ---------------------------------------------------------------------------------------
>
> Key: HADOOP-5073
> URL: https://issues.apache.org/jira/browse/HADOOP-5073
> Project: Hadoop Core
> Issue Type: Sub-task
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
>
> This jira proposes an interface classification for hadoop interfaces.
> The discussion was started in email alias [email protected] in Nov
> 2008.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
