You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@thrift.apache.org by "David Reiss (JIRA)" <ji...@apache.org> on 2011/02/08 19:24:57 UTC
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
[ 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