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

[Andrey Khropov]

Kamil Skalski wrote:

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

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

Yes,exactly. And Nemerledoc also don't like it.

> 
> > ----------------------------------------------------------------------------
> > ---- 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?

Initially I didn't came up with the idea. 

Exception is more complicated because it's description must have a body...

but maybe simple approach like

-----------------------------------------------
/// $[ 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>
///
-----------------------------------------------
will do?


[] instead of () to distinguish between links (see below) and description.

Next $[ ExceptionName : exception ] starts a new section.
Or just simply allow only one-paragraph descriptions.
Or use {}. 
Hmm, {} seem to be a more universal approach: see below.

But there're also <example>,<list>,<permission> and <value> remained uncovered.

Example often includes code quotes so maybe guard it with usual { } or #[ ]# 
(this combination is unlikely to appear in the code):

-----------------------------------------------
/// $[ :example ]#[
///   This is our nice $foreach macro:
///	<[
///     foreach(x in a)	
///		WriteLine(x);
///	]>
/// ]#
-----------------------------------------------
or
-----------------------------------------------
/// $[ :example ]{
///   This is our nice $foreach macro:
///	<[
///     foreach(x in a)	
///		WriteLine(x);
///	]>
/// }
-----------------------------------------------
':' before example to distinguish it from exception name, almost like anonymous 
(_ : example) or maybe allow naming examples and refer to them using $?

Like:

-----------------------------------------------
/// $[ foreach_macro_example : example ]{
///   This is our nice $foreach macro:
///	<[
///     foreach(x in a)	
///		WriteLine(x);
///	]>
/// }

...
/// ... see $foreach_macro_example ...
-----------------------------------------------

Maybe I've gone way too far?


Lists... Hmm 

Maybe use Pattern matching syntax :) :

() is a table header
 
-----------------------------------------------
/// $[ :list[table] ](Item,Description){
///    | item1 => description1
///    | item2 => Slighly longer description
/// }
-----------------------------------------------
is C#'s:
-----------------------------------------------
///<list type="table">
///    <listheader>
///        <term>Item</term>
///        <description>Description</description>
///    </listheader>
///    <item>
///        <term>item1</term>
///        <description>description1</description>
///    </item>
///    <item>
///        <term>item2</term>
///        <description>Slighly longer description</description>
///    </item>
///</list>
-----------------------------------------------

bulleted or numbered lists could be even simpler:

-----------------------------------------------
/// $[ : list[bullet] ]{
///    | item1 
///    | item2 
/// }
-----------------------------------------------

so Permission is then

-----------------------------------------------
/// $[ System.Security.PermissionSet : permission ] 
///   Everyone can access this method
///
-----------------------------------------------
is C#s
----------------------------------------------
/// <permission cref="System.Security.PermissionSet">
/// Everyone can access this method
/// </permission>
----------------------------------------------

Values then become 
----------------------------------------------
/// $[:value] true if this feature is enabled
----------------------------------------------


The general idea is to end tag block with the end of paragraph
or if we want to unite several paragraphs use {} 
or maybe #{ }# or #[ ]# (more visually distinguished!)

> > 
> > 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#?)

According to MSDN:

-------------------------------------------------------
<see cref="member"/>
 
Parameters
cref = " member" 
A reference to a member or field that is available to be called from the
current compilation environment. The compiler checks that the given code
element exists and passes member to the element name in the output XML. Place
member within double quotation marks (" ").
-------------------------------------------------------

Here is an MSDN entry for all the C# comments stuff:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclr
ftagsfordocumentationcomments.asp


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

Well, yes. Have you got any better thoughts?

I'm not terribly familiar with XPath (in fact I'm not familiar with it at all
:-) ).

Maybe $[ 'filename'.'path' ] as XPath refers to something that is inside the
file.
 or even $'filename'.'path'.

> > 
> > 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?

Well, it just simply came out to my mind as a most natural place for parameter
comments. In fact I often informally  write my parameter comments this way.

In a well-known 'doxygen' documentation system
post-entity comments are allowed with '///<' and '/**< ... */' syntax.

I think it's a little bit of overhead and '//<' is enough.
  
IMHO this can be handy for data members documentation too:

----------------------------------------------
[Record]
class ComplexNo
{
	public re : double; //< Real part
	public im : double; //< Imaginary part
}

----------------------------------------------

somewhat more readable than

----------------------------------------------
[Record]
class ComplexNo
{
	/// Real part
	public re : double; 

	/// Imaginary part
	public im : double;
}

----------------------------------------------

-- 
AKhropov