Mailing-List: contact issues-help@hbase.apache.org; run by ezmlm
Precedence: bulk
Date: Mon, 27 Oct 2014 15:37:33 +0000 (UTC)
From: "Jonathan Hsieh (JIRA)" <jira@apache.org>
To: issues@hbase.apache.org
Message-ID: <JIRA.12749557.1413913139000.344629.1414424253934@Atlassian.JIRA>
In-Reply-To: <JIRA.12749557.1413913139000@Atlassian.JIRA>
References: <JIRA.12749557.1413913139000@Atlassian.JIRA>
 <JIRA.12749557.1413913139650@arcas>
Subject: [jira] [Commented] (HBASE-12310) Remove custom doclet from
 hbase-annotations
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


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

Jonathan Hsieh commented on HBASE-12310:
----------------------------------------

The published javadoc pages are where I look and I where I assume users of hbase look (what is the alternative -- downloading the source jar or tarball?). 

If we only published one set of javadoc, the public user api be the one we should publish on the website.  Removing the doclet and only publishing the dev docs would expose and intermingle public with private apis.  It is very important to make it clear to users what the public user apis are, especially now that we are trying to define these as part of our compat policy. 

If we remove the doclet is there an simple alternative we could use to keep the distinction? (e.g. something less onerous than going and modify all private javadocs and enforcing this on review?)

> Remove custom doclet from hbase-annotations
> -------------------------------------------
>
>                 Key: HBASE-12310
>                 URL: https://issues.apache.org/jira/browse/HBASE-12310
>             Project: HBase
>          Issue Type: Bug
>            Reporter: Andrew Purtell
>
> hbase-annotations includes a custom doclet used for filtering APIs out of the user API javadoc given our project specific interface annotations. However, this is problematic for a few reasons:
> - To build the doclet we include a system scope dependency to tools.jar. Default Nexus rules disallow that. Staging downstream HBase artifacts will be problematic. I don't know how we were able to release 0.98.7 with this in place. I think someone will be looking into the Apache Nexus configuration.
> - As I understand it, system scope dependencies will not be supported by Maven 4 because they've been determined to be generally problematic. 
> - As [~busbey] mentioned on HBASE-12299, the root pom specifies the javadoc dependency for all modules and it creates a circular need with the hbase-annotations module.
> Do we really need a custom doclet? Can we simply remove all of this?


--
This message was sent by Atlassian JIRA
(v6.3.4#6332)