[jira] [Commented] (STORM-1218) Use Markdown Syntax for JavaDoc

["ASF GitHub Bot (JIRA)" <ji...@apache.org>]

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

ASF GitHub Bot commented on STORM-1218:
---------------------------------------

GitHub user ptgoetz opened a pull request:

    https://github.com/apache/storm/pull/891

    STORM-1218: Use markdown for JavaDoc

    JIRA: https://issues.apache.org/jira/browse/STORM-1218
    
    This is a first pass at converting the JavaDoc in `storm-core` to markdown, using [pegdown-doclet](https://github.com/Abnaxos/pegdown-doclet). If there is support from the community, I will move on to other components, though any html will just pass through, so it shouldn't garble, and will likely improve any existing javadoc.
    
    The first commit adds the corresponding maven javadoc plugin to the default build. This means it will increase build time when you run `mvn install`, but it will also spit out warnings about javadoc problems and may encourage developers to fix or improve documentation problems.
    
    The second commit is a quick pass over `storm-core` to remove unnecessary HTML and some minor javadoc comment linting. Only javadoc comments were modified.
    
    The third commit adds the `highlight.js` license to both the source and binary LICENSE files, since the generated javadoc includes it. I'm not sure this is necessary, since the JavaDoc is generated, but I will find out if there's support for this patch.
    
    *Note:* The [pegdown-doclet licence](https://github.com/Abnaxos/pegdown-doclet/blob/master/LICENSE.txt) is GPL, but it's only used at build time, so that does not seem to present a licensing issue.

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

    $ git pull https://github.com/ptgoetz/storm markdown-javadoc

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

    https://github.com/apache/storm/pull/891.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 #891
    
----
commit e03b28ca6222f61471b4acb1a6086aab9b597b8a
Author: P. Taylor Goetz <pt...@gmail.com>
Date:   2015-11-19T01:16:47Z

    enable markdown in javadoc

commit d6d85518bc7a668dfe7cad9e796c226752ad0aca
Author: P. Taylor Goetz <pt...@gmail.com>
Date:   2015-11-19T01:19:09Z

    convert existing javadoc to markdown

commit bc77f1f59622cff0e0bef01dfbc821ac3dba21c1
Author: P. Taylor Goetz <pt...@gmail.com>
Date:   2015-11-19T01:25:27Z

    add highlight.js licesnse to LICENSE files

----


> Use Markdown Syntax for JavaDoc
> -------------------------------
>
>                 Key: STORM-1218
>                 URL: https://issues.apache.org/jira/browse/STORM-1218
>             Project: Apache Storm
>          Issue Type: Bug
>            Reporter: P. Taylor Goetz
>            Assignee: P. Taylor Goetz
>
> Currently we use the standard HTML-based markup for our JavaDoc documentation, though many JavaDoc comments are not properly formatted. A good example of this multi-paragraph comments without {{<p/>}} tags, which leads to multiple paragraphs being squashed together.
> An easy fix for this is to switch to markdown for JavaDoc comments.
> Markdown format is also much easier to read in the context of code comments, and it's the format we use for our website and documentation.
> Switching to markdown may also encourage developers to better document their code, since it is less cumbersome.



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