hbase-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jonathan Hsieh (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (HBASE-12310) Remove custom doclet from hbase-annotations
Date Mon, 27 Oct 2014 15:37:33 GMT

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

Mime
View raw message