[Mono-list] Re: CS-Doc

[Gaurav Vaish]

Rhys: This mail is regarding where and how to collect document / comment
from cs file. My original mail is

http://lists.ximian.com/archives/public/mono-list/2003-February/012335.html


----- Original Message -----
From: "Miguel de Icaza" <miguel@ximian.com>
To: "Gaurav Vaish" <gvaish@adobe.com>
Cc: "Monkey Business" <mono-list@ximian.com>; "Paolo Molaro"
<lupus@ximian.com>
Sent: Thursday, February 20, 2003 23:01
Subject: [Mono-list] Re: CS-Doc


> Hello,
>
> > method_header
> >     : opt_attributes
> >       opt_modifiers
> >       type
> >       member_name
> >       OPEN_PARENS opt_formal_parameter_list CLOSE_PARENS
> >       {
> >            $$ = new Method (....., tokenizer.PullDocs ());
> >       }
> >     | ...
> > -----------
>
> The idea behind "PullDocs" was that it would return the
> documentation-so-far, and would reset the value to empty, and restart.

Doesn't make much of a difference if I pass another parameter to Method (and
others') ctor or do something like:

    $$ = new Method(...); // old stuff
    lexer.SaveDocFor($$); // (lexer is Tokenizer)

    The difference would be of the place where the documentation is stored.
In your case, it is with the object while in my case, it is with lexer -
which may be not a good idea.

    Now, the first part may (will) a overhauling of the mcs - since I
counted total of such objects to be 16 (Const, Field, Method, Property,
Inteface*, Operator, Constructor, Event, Delegate ... ... ...). So, I will
have to add another constructor for all or modify the existing ones. Or
another thing that I can do is add a public property Documentation (to the
class highest possible in hierarchy, like MethodCore or like) and then call:

    $$ = new Method(...); // old stuff
    $$.Documentation = lexer.PullDocs(); // public string Documentation
 get; set; }

    Anyway, the above does not solve my original problem, since tokenizer
will continue to collect documentation till CLOSE_PARENS is encountered, and
in the meanwhile will also tend to collect the ones that I gave example of
(included at the end for completeness).

    Thanks Adam for reminding me of P.Net's (Rhys') implementation of csdoc.
Rhys writes the rule as:

// P.Net
> ---------------------------------
> OptAttributes
>  : /* empty */   { $$ = 0; }
>  | AttributeSections { CSValidateDocs($1); MakeUnary(AttributeTree, $1); }
>  ;
> ---------------------------------


// My Idea. And mind you, it works fine with the 8 tests that I've written
so far.
--------------------------------------
opt_attributes
    : /* empty */ { lexer.StopCollectingDocument(); }
    | { lexer.StopCollectingDocument(); }
       attribute_sections { $$ = $2; }
    ;
--------------------------------------

// Test case under consideration
--------------------------------------
    /// <remarks>Nothing</remarks>
    public /// <summary>How about this?</summary>
        void MyMethod()
    {
    }
--------------------------------------




Happy Hacking,
Gaurav
http://mastergaurav.virtualave.net/iitk
---------------------------------------