Mailing-List: contact dev-help@zookeeper.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@zookeeper.apache.org
Date: Mon, 24 Jul 2017 22:36:02 +0000 (UTC)
From: "ASF GitHub Bot (JIRA)" <jira@apache.org>
To: dev@zookeeper.apache.org
Message-ID: <JIRA.13083859.1498842881000.1950.1500935762712@Atlassian.JIRA>
In-Reply-To: <JIRA.13083859.1498842881000@Atlassian.JIRA>
References: <JIRA.13083859.1498842881000@Atlassian.JIRA> <JIRA.13083859.1498842881434@jira-lw-us.apache.org>
Subject: [jira] [Commented] (ZOOKEEPER-2829) Interface usability /
 compatibility improvements through Java annotation.
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
archived-at: Mon, 24 Jul 2017 22:36:23 -0000


    [ https://issues.apache.org/jira/browse/ZOOKEEPER-2829?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16099209#comment-16099209 ] 

ASF GitHub Bot commented on ZOOKEEPER-2829:
-------------------------------------------

GitHub user afine opened a pull request:

    https://github.com/apache/zookeeper/pull/316

    ZOOKEEPER-2829: Interface usability / compatibility improvements through Java annotation.

    This patch uses Apache Yetus audience annotations to label our publicly available interfaces and then generate our javadoc based on the annotations. The javadoc generated by this patch should be identical to our javadoc before with a few extra classes (that I think should have been included before anyway). 
    
    HostProvider
    Record
    StaticHostProvider
    Transaction
    ZKClientConfig
    
    The "gotcha" with this patch is the way that java classes generated by jute are handled. There are four of these classes that need to be publicly documented: ACL, Id, Stat, StatPersisted (in addition to their superclass Record). I thought it would be safest to have the jute compiler always label these as "Public" and then we can filter out the ones we don't want in the javadoc ant task (by excluding the org.apache.zookeeper.server package and then pulling in the tools classes separately). 

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/afine/zookeeper ZOOKEEPER-2829

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/zookeeper/pull/316.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #316
    
----
commit c238a9f23787aade9122e7a9068b185d6c1fcf1b
Author: Abraham Fine <abefine@cloudera.com>
Date:   2017-07-24T22:11:43Z

    ZOOKEEPER-2829: Interface usability / compatibility improvements through Java annotation.

----


> Interface usability / compatibility improvements through Java annotation.
> -------------------------------------------------------------------------
>
>                 Key: ZOOKEEPER-2829
>                 URL: https://issues.apache.org/jira/browse/ZOOKEEPER-2829
>             Project: ZooKeeper
>          Issue Type: Improvement
>          Components: java client, server
>    Affects Versions: 3.4.10, 3.5.3
>            Reporter: Michael Han
>            Assignee: Abraham Fine
>              Labels: annotation
>
> Hadoop has interface classification regarding the interfaces' scope and stability. ZK should do something similar, which not only provides additional benefits of making API compatibility easier between releases (or even commits, by automating the checks via some tooling), but also consistent with rest of Hadoop ecosystem.
> See HADOOP-5073 for more context.


--
This message was sent by Atlassian JIRA
(v6.4.14#64029)