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 <[email protected]>
Date: 2015-11-19T01:16:47Z
enable markdown in javadoc
commit d6d85518bc7a668dfe7cad9e796c226752ad0aca
Author: P. Taylor Goetz <[email protected]>
Date: 2015-11-19T01:19:09Z
convert existing javadoc to markdown
commit bc77f1f59622cff0e0bef01dfbc821ac3dba21c1
Author: P. Taylor Goetz <[email protected]>
Date: 2015-11-19T01:25:27Z
add highlight.js licesnse to LICENSE files
----
---
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 [email protected] or file a JIRA ticket
with INFRA.
---
