[GitHub] spark issue #17389: [MINOR][BUILD] Fix javadoc8 break

[HyukjinKwon <gi...@git.apache.org>]

Github user HyukjinKwon commented on the issue:

    https://github.com/apache/spark/pull/17389
  
    I would like to to note that my observations.
    
    When we introduce a javadoc break, it seems sbt produces other warnings as errors when generating javadoc.
    There are currently so many warnings that are printed apprently as errors within generated java codes when there are javadoc breaks.
    
    For example,
    
    with the java code , `A.java`, below:
    
    ```java
    /**
    * Hi
    */
    public class A extends B {
    }
    ```
    
    if we run `javadoc`
    
    ```
    javadoc A.java
    ```
    
    it produces **warning** because it does not find B symbol. It seems still generating the documenation fine.
    
    ```
    Loading source file A.java...
    Constructing Javadoc information...
    A.java:4: error: cannot find symbol
    public class A extends B {
                           ^
      symbol: class B
    Standard Doclet version 1.8.0_45
    Building tree for all the packages and classes...
    Generating ./A.html...
    Generating ./package-frame.html...
    Generating ./package-summary.html...
    Generating ./package-tree.html...
    Generating ./constant-values.html...
    Building index for all the packages and classes...
    Generating ./overview-tree.html...
    Generating ./index-all.html...
    Generating ./deprecated-list.html...
    Building index for all classes...
    Generating ./allclasses-frame.html...
    Generating ./allclasses-noframe.html...
    Generating ./index.html...
    Generating ./help-doc.html...
    1 warning
    ```
    
    However, if we have a javadoc break in comments as below:
    
    ```java
    /**
    * Hi
    * @see B
    */
    public class A extends B {
    }
    ```
    
    this produces an **error**.
    
    ```
    Loading source file A.java...
    Constructing Javadoc information...
    A.java:5: error: cannot find symbol
    public class A extends B {
                           ^
      symbol: class B
    Standard Doclet version 1.8.0_45
    Building tree for all the packages and classes...
    Generating ./A.html...
    A.java:3: error: reference not found
    * @see B
           ^
    Generating ./package-frame.html...
    Generating ./package-summary.html...
    Generating ./package-tree.html...
    Generating ./constant-values.html...
    Building index for all the packages and classes...
    Generating ./overview-tree.html...
    Generating ./index-all.html...
    Generating ./deprecated-list.html...
    Building index for all classes...
    Generating ./allclasses-frame.html...
    Generating ./allclasses-noframe.html...
    Generating ./index.html...
    Generating ./help-doc.html...
    1 error
    1 warning
    ```
    
    and it seems somehow `sbt unidoc` recognises errors **and also warnings** as `[error]` when there are breaks.
    
    It seems okay to just fix `[info] 14 errors` which are usually generated in `Building tree for all the packages and classes...` phase.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org