[jira] [Comment Edited] (THRIFT-2320) Program level doctext does not get attached by parser

["Jens Geyer (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/THRIFT-2320?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13880510#comment-13880510 ] 

Jens Geyer edited comment on THRIFT-2320 at 1/23/14 11:36 PM:
--------------------------------------------------------------

Hi [~captncraig],

first of all: nice idea. 

After playing around a little with it, I quickly found out that your solution has problems when includes are used: in that case, the first include gets the program doctext assigned, while all other IDL files don't see their program doctext.

Next, the IDL allows for some ambiguities:

{code}
/** is this the doctext for the program or for the following type? */
struct Foo { 1: i32 bar }
{code}

While trying to fix both problems (the latter of the two in the best way possible) I finally more or less rewrote your entire patch and added some more changes to it.

I'd appreciate if you could review it.

h4. files
Use -gen html, seems to be the only place where it is actually used.
* [patch file version 2|^THRIFT-2320_program_doctext_v2.patch ]
* [first testcase|^testcase.zip]
* second testcase: tutorial IDL files




was (Author: jensg):
Hi [~captncraig],

first of all: nice idea. 

After playing around a little with it, I quickly found out that your solution has problems when includes are used: in that case, the first include gets the program doctext assigned, while all other IDL files don't see their program doctext.

Next, the IDL allows for some ambiguities:

{code}
/** is this the doctext for the program or for the following type? */
struct Foo { 1: i32 bar }
{code}

While trying to fix both problems (the latter of the two in the best way possible) I finally more or less rewrote your entire patch and added some more changes to it.

I'd appreciate if you could review it.

h4. files
* [patch file|^THRIFT-2320_program_doctext_v2.patch ]
* [first testcase|^testcase.zip]
* second testcase: tutorial IDL files



> Program level doctext does not get attached by parser
> -----------------------------------------------------
>
>                 Key: THRIFT-2320
>                 URL: https://issues.apache.org/jira/browse/THRIFT-2320
>             Project: Thrift
>          Issue Type: Improvement
>          Components: Compiler (General)
>    Affects Versions: 0.9.1
>            Reporter: Craig Peterson
>            Assignee: Jens Geyer
>         Attachments: THRIFT-2320_program_doctext_v2.patch, program_doctext.patch, testcase.zip
>
>
> I am using the html generator to generate documentation for our api. It would be really useful to define a block of text that outlines our service in general and how to use it. It looks like the data model has the capability to communicate a program level doc, and the html generator tries to use it, but it never gets stored onto the program object from the parser.



--
This message was sent by Atlassian JIRA
(v6.1.5#6160)