[jira] [Commented] (HBASE-17766) Generate Javadoc for hbase-spark module

["Yi Liang (JIRA)" <ji...@apache.org>]

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

Yi Liang commented on HBASE-17766:
----------------------------------

The reason why the scala source code API does not show up in javadoc is that our maven-javadoc-plugin does not recognize the .scala file, so it will only generate javadoc for the .java file under hbase-spark.

After investigate how spark generate javadoc for their scala&java mixed project, I found they use com.typesafe.genjavadoc plugin to generate javadoc for their scala file.

The approach the plugin taken here is to use the Scala compiler’s support as far as possible and then generate mostly valid Java code corresponding to the AST—but only the class and method structure without implementations, it means for each scala file, there is a corresponding java file generated but without implementation. And then use the maven-javadoc-plugin to generate javadoc based on each generated java code file.  and there is 1 limitation for this plugin:

In our current hbase javadoc, only @InterfaceAudience.public classes are shown. however this genjavadoc plugin does not recognize customized annotation in our project, when it generate java code, it will ignore those annotation in the scala code. 
But, this genjavadoc plugin can filter out private class in scala, We can change some public class with @InterfaceAudience.private to private Scala class, fortunately, in scala, even if we define some class as private, this private class can also be used in certain scope. For example private[spark] class A, it means this class A can be used under org.hadoop.hbase.spark package. And this method could filter most private class out of javadoc, but may not apply to only a few classes(1 or 2). And this priavet[scope] is also spark code style.

> Generate Javadoc for hbase-spark module 
> ----------------------------------------
>
>                 Key: HBASE-17766
>                 URL: https://issues.apache.org/jira/browse/HBASE-17766
>             Project: HBase
>          Issue Type: Bug
>            Reporter: Yi Liang
>            Assignee: Yi Liang
>             Fix For: 2.0.0
>
>
>  Scala classes in hbase-spark module aren't showing up in our API docs nor our internal API docs. 



--
This message was sent by Atlassian JIRA
(v6.3.15#6346)