[
https://issues.apache.org/jira/browse/HADOOP-14888?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16173865#comment-16173865
]
Eric Yang edited comment on HADOOP-14888 at 9/20/17 9:32 PM:
-------------------------------------------------------------
[~aw] Markdown requires developer to know that there are documentation written
somewhere else to match the code. It is easy to miss for new comers, then
someone else needs to spend time to realign document to code.
A couple examples from popular REST APIs:
[Google
Search|https://developers.google.com/custom-search/json-api/v1/using_rest]
[Instagram|https://developers.facebook.com/docs/instagram-api/reference/comments/]
[Apple
Music|https://developer.apple.com/library/content/documentation/NetworkingInternetWeb/Conceptual/AppleMusicWebServicesReference/FetchCharts.html#//apple_ref/doc/uid/TP40017625-CH4-SW1]
All those APIs have some similarity to Apidoc provided output. I can't say
they are using apidoc to generate the document, but they appear to be automated
to reduce maintenance cost. This is only a recommendation for improvement.
Let see if there are other ideas to make Hadoop developer life easier.
was (Author: eyang):
[~aw] Markdown requires developer to know that there are documentation written
somewhere else to match the code. It is easy to miss for new comers, then
someone else need to spend time to realign document to code.
A couple examples from popular REST APIs:
[Google
Search|https://developers.google.com/custom-search/json-api/v1/using_rest]
[Instagram|https://developers.facebook.com/docs/instagram-api/reference/comments/]
[Apple
Music|https://developer.apple.com/library/content/documentation/NetworkingInternetWeb/Conceptual/AppleMusicWebServicesReference/FetchCharts.html#//apple_ref/doc/uid/TP40017625-CH4-SW1]
All those APIs have some similarity to Apidoc provided output. I can't say
they are using apidoc to generate the document, but they appear to be automated
to reduce maintenance cost. This is only a recommendation for improvement.
Let see if there are other ideas to make Hadoop developer life easier.
> Use apidoc for REST API documentation
> -------------------------------------
>
> Key: HADOOP-14888
> URL: https://issues.apache.org/jira/browse/HADOOP-14888
> Project: Hadoop Common
> Issue Type: Improvement
> Components: build, documentation
> Reporter: Eric Yang
> Assignee: Eric Yang
>
> There are more REST API being developed in Hadoop, and it would be great to
> standardize on the method of generate REST API document.
> There are several method done today:
> Swagger YAML
> Javadoc
> Wiki pages
> JIRA comments
> The most frequently used method is JIRA comments and Wiki pages. Both
> methods are prone to data loss through passage of time. We will need a more
> effortless approach to maintain REST API documentation. Swagger YAML can
> also be out of sync with reality, if new methods are added to java code
> directly. Javadoc annotation seems like a good approach to maintain REST API
> document. Both Jersey and Atlassian community has maven plugin to help
> generating REST API document, but those maven plugins have ceased to
> function. After searching online for REST API documentation for a bit,
> [apidoc|http://apidocjs.com/] is one library that stand out. This could be
> the ideal approach to manage Hadoop REST API document. It supports javadoc
> like annotations, and generate beautiful schema changes documentation.
> If this is accepted, I will add apidoc installation to dev-support
> Dockerfile, and pom.xml changes for javadoc plugin to ignore the custom tags.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: common-issues-unsubscr...@hadoop.apache.org
For additional commands, e-mail: common-issues-h...@hadoop.apache.org
