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

[NoiseEHC]

I would strongly suggest that we should not treat case 1) and 3) as 
legal, so we should force the use of xml comments (2).
If it would be too much work then I will go trough the nemerle codebase 
and 'prettyze' comments.
BTW it is new to me that xml comments work in /** ... */ Maybe I am not 
that C# king? :)
With the other tags I would suggest to have 99% C# compatibility. What I 
would like to see some easier method to include
comment for params so that is the only thing I would call acceptable.

ps:
What is this google group? Is devel-en is obsolete?

Andrey Khropov wrote:
> 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) ?
>  
>