[Mono-list] CS-Doc

[Gaurav Vaish]

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:

--------------------------------------
method_header
    : opt_attributes
      opt_modifiers
      type
      member_name
      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
etc.
    So, I think, I need to modify the rule to:

--------------------------------------
opt_attributes
    : /* 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,
Gaurav
http://sourceforge.net/projects/csdoc
-----------------------------------