[nem-en] Documentation comments clarification and proposals [Long]

[Kamil Skalski]

> ).
> So either mixing of such XML/non-XML summary/remarks should be disallowed
> (so only implicit form is possible (like in 1) )
>  and 3) is considered improperly formed and reported by the compiler(warning).
> Or compiler should recognize when we explicitly write tags and then 3) is
> equivalent to 1) and 2)

At first sight, disallowing mixing seems to be a good approach, but as
we need to detect if there is <summary> tag, I think we should also do
the same for <remarks>. As I see in code (ncc/hierarchy/XmlDump.n) we
do not do this for either <summary> or <remarks> :)  So probably
example 2) will produce also double <summary> tag...

> --------------------------------------------------------------------------------
> Ok, now what's about other tags (I think we probably should stay close to C#
> model because Intellisense and Object browser use it)
> (* denotes compiler-checked statements)

I would like to say that I like most of your ideas. At last there is
somebody who wrote down something like specification for this stuff.
It is a very good starting point.

> <exception>*            - describes exceptions that may be thrown from the code

* ?   Which construct would you propose here?

>
> So I think it wouldn't be a bad idea to reuse some constructs we can find in
> the core Nemerle language.

This is a very simple, but extremely smart idea :D

> For example:
>  1) Use <[ ... ]> for code (multiline is of course allowed):
>         <[some code]> is equivalent to
>
>         <code>some code</code>

I agree in 100%

>
>  2) Use $ for links       : $x refers to some symbol, is equivalent to :
>                 <paramref name="x"/> or
>                 <see name="x"/> or
>                 <typeparamref name="x"/>
>
>         Which of these should be picked can be inferred unambigoulsy in most cases      or
> we could explicitly provide annotation:
>
>         $( x : param ), $( x : see ) or $( x : typeparam )

Yes, I think it could relatively easy resolve to (in decreasing priority):
- paramref
- typeparamref of method
- typeparamref of class
- any visible method / type
- warning if it does not match anything / is ambiguous

(BTW, how does "see" work in C#?)

>
>  3) XPath links could be represented as
>
>         $['filename' | 'path']   is equivalent to
>
>         <include file='filename' path='path' />

Well, I'm not really sure this is a good idea. $[ | ] syntax has
nothing to do with including anything...

>
> Paragraphs can be subdivided simply by blank lines (as in TeX).

Agree.

>
> And I also believe that parameters and return value should be annotated in such
> a way (why retype their names in comments anyway):

Hm, this is a point for discussion. It looks like a nice idea, but it
could become a little bit strange and hard to format nicely. And
especially, what about the rule, that commend comes BEFORE element it
comments?

As for implementation notes:
- I think that it is not really possible / feasible to reuse standard
compiler's parsing procedures. From the proposed stuff we just need to
catch the <[ ]>, $ and $(..) syntax,
so it should be possible to write a simple state automata.
- I would definitely help with code for resolving the $XX names, as it
is easy when you know some compiler internals


-- 
Kamil Skalski
http://nazgul.omega.pl