You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@thrift.apache.org by "John Bartak (JIRA)" <ji...@apache.org> on 2010/01/19 20:18:54 UTC
[jira] Created: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
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
Affects Versions: 0.2
Reporter: John Bartak
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.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
John Bartak updated THRIFT-681:
-------------------------------
Attachment: t_html_generator_JavaDoc.patch
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Issue Comment Edited: (THRIFT-681) The HTML generator does
not handle JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802457#action_12802457 ]
John Bartak edited comment on THRIFT-681 at 1/19/10 8:32 PM:
-------------------------------------------------------------
The section from the .thrift file that generated the attached screenshot:
/**
\* Changes a message's status
\* @param personId the person changing the status
\* @param messageId the message to change the status of
\* @param newStatus the new status of the message
\* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
was (Author: johnbartak):
The section from the .thrift file that generated the attached screenshot:
/**
* Changes a message's status
* @param personId the person changing the status
* @param messageId the message to change the status of
* @param newStatus the new status of the message
* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "Lars Francke (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12803158#action_12803158 ]
Lars Francke commented on THRIFT-681:
-------------------------------------
About the duplicated parameters: Have a look at the file David pointed out to you. It shows how function parameters ought to be documented.
I'm using the comment style from the DocTest.thrift but there is no documentation generated for function parameters either:
{noformat}
/**
* Disables a table (takes it off-line) If it is being served, the master
* will tell the servers to stop serving it.
*/
void disableTable(
/** name of the table */
1:Bytes tableName
) throws (1:IOError io)
{noformat}
It would be nice if this format would be supported by the HTML compiler. The output your patch produces looks very nice. I think it would be good if that patch was adapted so it uses this "official" documentation style. It would be even nicer if this style was documented somewhere outside of the test. I'll try to find a place in the wiki tomorrow where this fits.
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "Roger Meier (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Roger Meier updated THRIFT-681:
-------------------------------
Component/s: Compiler (General)
> 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-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "David Reiss (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802424#action_12802424 ]
David Reiss commented on THRIFT-681:
------------------------------------
See test/DocTest.thrift for the proper way of documenting parameters. We don't have an example for exceptions, but they work the same 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
> Affects Versions: 0.2
> Reporter: John Bartak
>
> 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.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
John Bartak updated THRIFT-681:
-------------------------------
Attachment: screenshot-1.jpg
Atttached screenshot showing result of using this patch
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Issue Comment Edited: (THRIFT-681) The HTML generator does
not handle JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802457#action_12802457 ]
John Bartak edited comment on THRIFT-681 at 1/19/10 8:38 PM:
-------------------------------------------------------------
The section from the .thrift file that generated the attached screenshot:
{code}
/**
* Changes a message's status
* @param personId the person changing the status
* @param messageId the message to change the status of
* @param newStatus the new status of the message
* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws
(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException
revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
{code}
The Java compiler generates the following code from the above definition:
{code}
/**
* Changes a message's status
* @param personId the person changing the status
* @param messageId the message to change the status of
* @param newStatus the new status of the message
* @exception AccessDeniedException thrown if the person does not have access to the message
*
* @param personId
* @param messageId
* @param newStatus
*/
public void UpdateMessageStatus(String personId, String messageId, com.autodesk.social.serviceContracts.Message.Status newStatus)
throws com.autodesk.social.serviceContracts.SocialException, com.autodesk.social.serviceContracts.SocialDatabaseException,
com.autodesk.social.serviceContracts.BadRevisionException, com.autodesk.social.serviceContracts.ResourceNotFoundException,
com.autodesk.social.serviceContracts.AccessDeniedException, TException;
{code}
This isn't totally ideal since the parameters get duplicated -- but that seems like more of an issue with the Java compiler.
was (Author: johnbartak):
The section from the .thrift file that generated the attached screenshot:
/**
\* Changes a message's status
\* @param personId the person changing the status
\* @param messageId the message to change the status of
\* @param newStatus the new status of the message
\* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
The Java compiler generates the following code from the above definition:
/**
* Changes a message's status
* @param personId the person changing the status
* @param messageId the message to change the status of
* @param newStatus the new status of the message
* @exception AccessDeniedException thrown if the person does not have access to the message
*
* @param personId
* @param messageId
* @param newStatus
*/
public void UpdateMessageStatus(String personId, String messageId, com.autodesk.social.serviceContracts.Message.Status newStatus) throws com.autodesk.social.serviceContracts.SocialException, com.autodesk.social.serviceContracts.SocialDatabaseException, com.autodesk.social.serviceContracts.BadRevisionException, com.autodesk.social.serviceContracts.ResourceNotFoundException, com.autodesk.social.serviceContracts.AccessDeniedException, TException;
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "David Reiss (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802462#action_12802462 ]
David Reiss commented on THRIFT-681:
------------------------------------
Yeah, I'm pretty sure what is going on here is that the compiler is just byte-copying your javadoc-style comment from the thrift file to the java file. Try using docblock comments on the parameters themselves (see that file I pointed to).
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802457#action_12802457 ]
John Bartak commented on THRIFT-681:
------------------------------------
The section from the .thrift file that generated the attached screenshot:
/**
* Changes a message's status
* @param personId the person changing the status
* @param messageId the message to change the status of
* @param newStatus the new status of the message
* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802426#action_12802426 ]
John Bartak commented on THRIFT-681:
------------------------------------
The Java compiler inserts the comments from the .thrift file into the generated .java file. So it would be nice if the HTML compiler respected the JavaDoc style comments.
I will be attaching a patch that actually does this.
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
>
> 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.
-
You can reply to this email to add a comment to the issue online.
[jira] Issue Comment Edited: (THRIFT-681) The HTML generator does
not handle JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802457#action_12802457 ]
John Bartak edited comment on THRIFT-681 at 1/19/10 8:34 PM:
-------------------------------------------------------------
The section from the .thrift file that generated the attached screenshot:
/**
\* Changes a message's status
\* @param personId the person changing the status
\* @param messageId the message to change the status of
\* @param newStatus the new status of the message
\* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
The Java compiler generates the following code from the above definition:
/**
* Changes a message's status
* @param personId the person changing the status
* @param messageId the message to change the status of
* @param newStatus the new status of the message
* @exception AccessDeniedException thrown if the person does not have access to the message
*
* @param personId
* @param messageId
* @param newStatus
*/
public void UpdateMessageStatus(String personId, String messageId, com.autodesk.social.serviceContracts.Message.Status newStatus) throws com.autodesk.social.serviceContracts.SocialException, com.autodesk.social.serviceContracts.SocialDatabaseException, com.autodesk.social.serviceContracts.BadRevisionException, com.autodesk.social.serviceContracts.ResourceNotFoundException, com.autodesk.social.serviceContracts.AccessDeniedException, TException;
was (Author: johnbartak):
The section from the .thrift file that generated the attached screenshot:
/**
\* Changes a message's status
\* @param personId the person changing the status
\* @param messageId the message to change the status of
\* @param newStatus the new status of the message
\* @exception AccessDeniedException thrown if the person does not have access to the message
*/
void UpdateMessageStatus(1:string personId,2:string messageId,3:MessageData.Status newStatus) throws(1:Shared.SocialException socialError,2:Shared.SocialDatabaseException databaseError,3:Shared.BadRevisionException revisionException,4:Shared.ResourceNotFoundException notFoundException,5:Shared.AccessDeniedException accessError),
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "John Bartak (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12803358#action_12803358 ]
John Bartak commented on THRIFT-681:
------------------------------------
I'm also concerned about the readability of the documentation in the .thrift file. I think it is easier to read the JavaDoc style comments than putting each parameter on a separate line with a comment above it.
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (THRIFT-681) The HTML generator does not handle
JavaDoc style comments very well
Posted by "David Reiss (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/THRIFT-681?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12802450#action_12802450 ]
David Reiss commented on THRIFT-681:
------------------------------------
Can you provide an example .thrift file to demonstrate what you mean by "The Java compiler inserts the comments from the .thrift file into the generated .java file."?
> 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
> Affects Versions: 0.2
> Reporter: John Bartak
> Attachments: screenshot-1.jpg, t_html_generator_JavaDoc.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.
-
You can reply to this email to add a comment to the issue online.