[Mono-bugs] [Bug 79706][Wis] New - gmcs /doc doesn't like generic types

[bugzilla-daemon at bugzilla.ximian.com]

Please do not reply to this email- if you want to comment on the bug, go to the
URL shown below and enter your comments there.

Changed by jonpryor at vt.edu.

http://bugzilla.ximian.com/show_bug.cgi?id=79706

--- shadow/79706	2006-10-20 07:38:29.000000000 -0400
+++ shadow/79706.tmp.2752	2006-10-20 07:38:29.000000000 -0400
@@ -0,0 +1,123 @@
+Bug#: 79706
+Product: Mono: Compilers
+Version: 1.1
+OS: 
+OS Details: 
+Status: NEW   
+Resolution: 
+Severity: 
+Priority: Wishlist
+Component: C#
+AssignedTo: rharinath at novell.com                            
+ReportedBy: jonpryor at vt.edu               
+QAContact: mono-bugs at ximian.com
+TargetMilestone: ---
+URL: 
+Cc: 
+Summary: gmcs /doc doesn't like generic types
+
+Please fill in this template when reporting a bug, unless you know what you
+are doing.
+Description of Problem:
+
+gmcs /doc doesn't properly support generic types & members.
+
+Take the following code:
+
+	// gmcs documents generic members incorrectly
+	using System.Collections.Generic;
+
+	namespace Test {
+		/// <remarks>T:Test.DocMe</remarks>
+		/// <seealso cref="T:Test.DocMe`1" />
+		class DocMe {
+
+			///
+<remarks>M:Test.DocMe.UseList(System.Collections.Generic.List{System.Int32})</remarks>
+			public static void UseList (List<int> list) {}
+
+			/// <remarks>M:Test.DocMe.Main</remarks>
+			public static void Main ()
+			{
+			}
+		}
+
+		/// <remarks>T:Test.DocMe`1</remarks>
+		class DocMe<T> {
+			///
+<remarks>M:Test.DocMe`1.UseList(System.Collections.Generic.List{`0})</remarks>
+			public void UseList (List<T> list) {}
+
+			///
+<remarks>M:Test.DocMe`1.UseList`1(System.Collections.Generic.List{``0})</remarks>
+			public void UseList<U> (List<U> list) {}
+
+			/// <remarks>M:Test.DocMe`1.RefMethod`1(`0@,``0@)</remarks>
+			public void RefMethod<U> (ref T t, ref U u) {}
+		}
+	}
+
+Compile the aboce code with: gmcs /doc:gendoc.xml gendoc.cs
+
+There are three problems with `gmcs /doc' support for the above code:
+
+1. It generates a warning CS1584 for the <seealso cref="T:Test.DocMe`1"/>.
+ AFAIK, this is a valid cref, so a warning should not be generated. 
+(Furthermore, within the xml the T:Test.DocMe`1 becomes !:Test.DocMe`1 --
+an error prefix -- and this shouldn't happen either.)
+
+2. It generates an error CS1569 "Error generating XML documentation file
+`gendoc.xml' (`Object reference not set to an instance of an object')"
+(i.e. an internal NullReferenceException) when attempting to handle
+M:Test.DocMe`1.RefMethod`1.  Remove the comment on RefMethod<U>() and it
+will generate documentation normally, but this shouldn't happen.
+
+3. Once (2) is fixed (or the RefMethod comment is removed), look at the
+generated gendoc.xml.  It has incorrect member string IDs.  (The doc
+comments include the "correct" XML IDs.)  See also Ecma-334 3rd edition,
+Annex E (in particular, E.3.1, the final "bullet" which begins "For methods
+and properties with arguments, the argument list follows...".
+
+For example, with the member:
+
+	public static void UseList (List<int> list) {}
+
+the string ID generated is:
+
+        <member
+name="M:Test.DocMe.UseList(System.Collections.Generic.List`1[[System.Int32,
+mscorlib, Version=2.0.0.0, Culture=neutral,
+PublicKeyToken=b77a5c561934e089]])">
+
+It *should* be:
+
+        <member
+name="M:Test.DocMe.UseList(System.Collections.Generic.List{System.Int32})">
+
+Similarly, for:
+
+	public void UseList (List<T> list) {}
+
+The string ID generated is:
+
+        <member
+name="M:Test.DocMe`1.UseList(System.Collections.Generic.List`1[T])">
+
+It *should* be:
+
+        <member
+name="M:Test.DocMe`1.UseList(System.Collections.Generic.List{`0})">
+
+(as per Annex E.3.1).
+ 
+Finally, if I understand Annex E properly, the compiler should support
+replacing type parameters with the type position within ID strings.
+
+For example, a <see cref="M:Test.DocMe{T}.UseList(List{T})/> reference
+within the .cs file would need to be transformed into a <see
+cref="M:Test.DocMe`1.UseList(System.Collections.Generic.List{`0})"/> (in
+which T is replaced with `0).
+
+For good measure, this should all be verified against CSC 2.0 (I don't have
+any access to it), but from my understanding of Annex E this should all be
+correct.