[nem-en] Re: Documentation comments proposals [Very Long]

[Kamil Skalski]

> I propose a model that is semantically equivalent to C# XML comments
> but with a simpler syntax.
>
> /// <sometag cref="name">Some description</sometag>
>
> just translates to
>
> /// $[ name : sometag ] Some description

I'm not really sure this is *simpler* syntax:
- it's not clear when paragraph ends
- $[ x : y]  syntax hits your eyes with unfamiliarity, since there is
no equivalent construct in Nemerle or other similar languages
- it is not clear which part refers to original XML tag name and which
to (removed!!) attribute name "cref"

Your original ideas are nice, because they are based on "familiarity"
concept - <[ ]> and $ are common (at least in advanced) Nemerle code
and there will be rather little surprise to see them in doc comments.


>
> I actually think that we should either totally reinvent the wheel (only
> syntactically, not semantically) or stick to some already available syntax (be
> it C# XML comments or Javadoc).

I guess we should rather keep the "least surprise" rule if we can.
Inventing completely new syntax used only in one place makes no sense
to me. But simplifying the existing well known syntax with consistent
and also known constructs makes sense.

>
> Making "something like C# XML but with a few shortcuts" will only confuse
> people.

Why do you think so?



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