[
https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12992087#comment-12992087
]
David Reiss commented on THRIFT-681:
------------------------------------
My preference is for the latter. I disagree with John's last comment.
Specifically, I think it is easier to have the docs exist once right next to
the parameter they refer to, rather than have the docs all clustered at the top
with the names repeated (or out-of-sync) and no immediate indication of the
type.
Kind of like having a docblock above each method, rather than just having them
all at the top of the class.
Another way I think of it is that the arguments are like members of a structure
that are being sent along with the RPC, and the structure members are
documented individually.
That said, I don't think it would destroy the Thrift project if we went the
other way.
> The HTML generator does not handle JavaDoc style comments very well
> -------------------------------------------------------------------
>
> Key: THRIFT-681
> URL: https://issues.apache.org/jira/browse/THRIFT-681
> Project: Thrift
> Issue Type: Improvement
> Components: Compiler (General)
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: Screenshot.png, screenshot-1.jpg,
> t_html_generator_JavaDoc.patch, t_html_generator_JavaDoc.v2.patch,
> thrift-682-v2.patch
>
>
> If you create comments using the standard JavaDoc conventions of @param and
> @exception, the output that gets generated isn't the cleanest. It would be
> better if the list of parameters and exceptions were placed in a table with
> the appropriate headers rather than just outputting the @param and @exception
> tags into the HTML output.
--
This message is automatically generated by JIRA.
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
