You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@storm.apache.org by ptgoetz <gi...@git.apache.org> on 2015/11/19 02:50:12 UTC
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
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
----
---
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.
---
Re: [GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by Cody Innowhere <e....@gmail.com>.
+1. Cool.
(However the pegdown doclet plugin for IDEA doesn't work -_-)
On Thu, Nov 26, 2015 at 1:01 AM, harshach <gi...@git.apache.org> wrote:
> Github user harshach commented on the pull request:
>
> https://github.com/apache/storm/pull/891#issuecomment-159672448
>
> +1. Thanks this will make doc writing easier.
>
>
> ---
> 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.
> ---
>
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by harshach <gi...@git.apache.org>.
Github user harshach commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-159672448
+1. Thanks this will make doc writing easier.
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by ptgoetz <gi...@git.apache.org>.
Github user ptgoetz commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-158109736
@revans2 Yes, it is inserted into the generated HTML. Since javadoc isn't part of the source release, it probably only needs to be added to the LICENSE for the binary distribution.
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by redsanket <gi...@git.apache.org>.
Github user redsanket commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-161136973
NB +1
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/storm/pull/891
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by harshach <gi...@git.apache.org>.
Github user harshach commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-161149510
Thanks @ptgoetz merged into master.
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by ptgoetz <gi...@git.apache.org>.
Github user ptgoetz commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-159371834
I removed the highlight.js license from the source release LICENSE file since generated javadoc is not part of a source release.
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by ptgoetz <gi...@git.apache.org>.
Github user ptgoetz commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-157928854
Re: Merge conflicts, I'm happy to resolve therm at merge time.
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by revans2 <gi...@git.apache.org>.
Github user revans2 commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-158086449
I am +1 on the concept. I don't see where highlight.js is added to the codebase. It is automatically inserted into the created javadocs?
---
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.
---
[GitHub] storm pull request: STORM-1218: Use markdown for JavaDoc
Posted by ptgoetz <gi...@git.apache.org>.
Github user ptgoetz commented on the pull request:
https://github.com/apache/storm/pull/891#issuecomment-159422903
**Note:** This pull request originally included the following commit: https://github.com/apache/storm/commit/e03b28ca6222f61471b4acb1a6086aab9b597b8a
Earlier today I inadvertently pushed that commit to master. I have since reverted it in master. The last commit in this PR re-adds what was reverted, but only in my repository.
---
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.
---