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

[Michal Moskal]

On 11/10/06, Andrey Khropov <andrey.khropov at gmail.com> wrote:
> /// $[ ArgumentException : exception ] Thrown when argument is wrong
> ///
> /// $[ NotImplementedException : exception ] Thrown when feature
> ///  is not implemented
> /// ...
> ///
> -----------------------------------------------
> equivalent to C#'s
> -----------------------------------------------
> /// <exception cref="ArgumentException">
> ///  Thrown when argument is wrong
> /// </exception>
> ///
> /// <exception cref="NotImplementedException">
> ///     Thrown when feature is not implemented
> /// </exception>
> ///

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

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

> <see cref="member"/>

And I would be for just $member here.

-- 
   Michał