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

[Andrey Khropov]

Michal Moskal wrote:

> I think, we're going to far. Skipping <para>, <summary>, <remarks>
> (with empty lines) makes perfect sense and is obvious what it means
> (maybe except that the first para is summary, but one can argue about
> it).
The same rules are used in doxygen.

> Using some quoting for code and inline descriptions for
> parameters should be also clear from context, but this one I think
> goes a bit too far. Maybe just allow </> to be a closing tag? So we
> would have:
> 
> /// <exception cref="ArgumentException">  Thrown when argument is wrong </>
> 
> which isn't much longer, generalizes well (folks could also use it for
> <param>, <permissions> and the like) and is immediately clear for
> people using C# before.
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

 So I think it could be quite comprehensible 
by C# users.

> 
> The point is that we don't have to reinvent the wheel, just provide a
> few shortcuts to make writing this comments easier.

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).

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

So I'm for either something like my shorthand notation (which is *semantically*
equivalent to C# XML) or full-fledged XML fully compatible with C#.
(I think both can co-exist and can be chosen by compiler/external documenter
switches).

-- 
AKhropov