[GitHub] spark pull request #16050: [SPARK-18615][DOCS] Switch to multi-line doc to a...

[HyukjinKwon]

GitHub user HyukjinKwon opened a pull request:

    https://github.com/apache/spark/pull/16050

    [SPARK-18615][DOCS] Switch to multi-line doc to avoid a genjavadoc bug for 
backticks

    ## What changes were proposed in this pull request?
    
    Currently, single line comment does not mark down backticks to 
`<code>..</code>` but prints as they are (`` `..` ``). For example, the line 
below:
    
    ```scala
    /** Return an RDD with the pairs from `this` whose keys are not in `other`. 
*/
    ```
    
    So, we could work around this as below:
    
    ```scala
    /**
     * Return an RDD with the pairs from `this` whose keys are not in `other`.
     */
    ```
    
    - javadoc
    
      - **Before**
        ![2016-11-29 10 39 
14](https://cloud.githubusercontent.com/assets/6477701/20693606/e64c8f90-b622-11e6-8dfc-4a029216e23d.png)
    
      - **After**
        ![2016-11-29 10 39 
08](https://cloud.githubusercontent.com/assets/6477701/20693607/e7280d36-b622-11e6-8502-d2e21cd5556b.png)
    
    - scaladoc (this one looks fine either way)
    
      - **Before**
        ![2016-11-29 10 38 
22](https://cloud.githubusercontent.com/assets/6477701/20693640/12c18aa8-b623-11e6-901a-693e2f6f8066.png)
    
      - **After**
        ![2016-11-29 10 40 
05](https://cloud.githubusercontent.com/assets/6477701/20693642/14eb043a-b623-11e6-82ac-7cd0000106d1.png)
    
    I suspect this is related with SPARK-16153 and genjavadoc issue in ` 
typesafehub/genjavadoc#85`.
    
    ## How was this patch tested?
    
    I found them via `grep -r "\/\*\*.*\`" . | grep .scala` and then checked if 
each is in the public API documentation with manually built docs (`jekyll 
build`) with Java 7.
    


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

    $ git pull https://github.com/HyukjinKwon/spark javadoc-markdown

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

    https://github.com/apache/spark/pull/16050.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 #16050
    
----
commit d62ac242e741a8c2f55b3a4a42090609a56fcd64
Author: hyukjinkwon <gurwls...@gmail.com>
Date:   2016-11-29T01:29:33Z

    Work around genjavadoc bug

----


---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

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