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

[Andrey Khropov]

Hello all!

There was some discussion on the subject here:
http://groups.google.com/group/nemerle-en/browse_thread/thread/3194b4b4d96c1c72
and here:
http://groups.google.com/group/nemerle-en/browse_thread/thread/8d1542dea07c1ad0

but I finally want to have an exact specification.

If I recall correctly the idea was to use generally the same form for doc
comments ( /// ... or /**  */ ) as in C# but allow (but not require?) omitting
of <summary> statements and also when comment is subdivided by empty line(s?)
then the first part is treated like summary and the second is like remarks:

1)
/**
 *  This is summary
 *
 *  This is remarks
 *
 */

is equivalent to C#'s

2)
/**
 *  <summary>This is summary</summary>
 *
 *  <remarks>This is remarks</remarks>
 *
 */

But we should be careful treating mixed cases
(and such cases are really present in existing compiler codebase now!):

3)
/**
 *  This is summary 
 *
 *  <remarks>This is remarks</remarks>
 *
 */

In the present state of the compiler it produces double <remarks> tags
(<remarks><remarks>This is remarks</remarks></remarks>)
This is obviously is not what we want ( and Nemerledoc doesn't like it also :-)
).
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)
--------------------------------------------------------------------------------
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)
:

<c>    	   		- inline code
<code> 	   		- multiline code
<example>			- example how to use (typically paired with <code>)
<exception>*		- describes exceptions that may be thrown from the code
<include>*			- reference to the other file with XPath syntax
<list>			- lists
<para> 			- paragraph
<param>*			- used to describe parameters
<paramref>			- reference to the parameter in the comment
<permission>*		- documents permission-related information
<remarks>			- just remarks
<returns>			- describes return value
<see>*			- reference to some type/method
<seealso>*			- same as see but is passed to the "See also" doc section
later
<summary>			- main comment
<typeparam>*		- type parameter description  (for generics)
<typeparamref>		- reference to type parameter (for generics)
<value>			- description for the property value

As Nemerle is all about conciseness ;-) I think we should provide some lighter
alternative syntax constructs for these tags.

So I think it wouldn't be a bad idea to reuse some constructs we can find in
the core Nemerle language.
For example:
 1) Use <[ ... ]> for code (multiline is of course allowed):
	<[some code]> is equivalent to 

	<code>some code</?ode>

 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 )		

 3) XPath links could be represented as

	$['filename' | 'path']   is equivalent to 

	<include file='filename' path='path' />

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

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

------------------------------------
///
///	Program entry point
///
public ComputeForce( m  : double, 		/// represents mass in kgs
		  		a  : Vec3[double] )  /// represents acceleration as a 3d 									///
vector in m/s
				: Vec3[double]		/// Force = $m * $a
------------------------------------
or
------------------------------------
/**
	Program entry point
*/
public ComputeForce( m  : double, 		/** represents mass in kgs */
		  		a  : Vec3[double] )  /** represents acceleration as a 3d
vector in m/s */
				: Vec3[double]		/** Force = $m * $a */
------------------------------------

But I haven't figured out yet how to fit generics in this picture.
And how to provide documentation for macros (do we need any additional
constructs?)


I also think that all XML should be legal as well because it'll simplify code
porting from C#.


So, what do you think about all this stuff (maybe I totally miss the point and
it's almost impossible or very slow to implement proposed things) ?
 
-- 
AKhropov