[Mono-list] CS-Doc

Gaurav Vaish gvaish@adobe.com
Thu, 20 Feb 2003 19:40:25 +0530

Hi (especially Miguel and Lupus),

    I am currently hacking mcs to come up with csdoc - C# Document Generator
using inline documentation, but hung up in a strange but destined situation.

    Let me demonstrate using an example:

    The non-terminal is "method_header" (line 855 in cs-parser.jay of mcs),
and the rule is:

    : opt_attributes
      OPEN_PARENS opt_formal_parameter_list CLOSE_PARENS
    | ...

    The grammar is absolutely correct (obviously), but I collect the
documentation inside { ... }, after there is "Method method = new
Method(...)", and this creates a problem.

    Consider the following situation:

    /// <remarks>Nothing</remarks>
    public /// <summary>How about this?</summary>
        void MyMethod()

    Now, the above declaration is correct, but I also collect this summary,
which I should not! As such, there's a need to modify the grammar slightly.
But also, I need for all objects - class, interface, event, property,
indexers etc.

    The best place(s) that I think of is to put it in "opt_attributes" (line
424), since it appears before everything - class, method, event, property
    So, I think, I need to modify the rule to:

    : /* empty */ { lexer.StopCollectingDocument(); }
    | { lexer.StopCollectingDocument(); }
       attribute_sections { $$ = $2; }

    Wherein the lexer::StopCollectingDocument() will give a signal (set a
flag) to not to collect any more comment until lexer::SaveDocumentFor(...)
is called which resets the flag.

    But I am confused as to whether what I am doing is right or not - I
mean, I am doing something even before I hit something (attribute_sections
or EMPTY) and I think this is absolutely absurd.

    Can anyone guide me - how to overcome this scenario? Where to set my
flag, if at all? Or at the worst, do I keep it as a "known issue"?

Happy Hacking,