[Mono-docs-list] Differences between generic names in the documentation.

[Jonathan Pryor]

On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> I recently tried to work on the generics support in monodocer and
> noticed that it has names one and the same type differently.
> 
> Eg: If i have a "public class Test<T>" monodocer will produce the
> following output.
> 
> index.xml:
> 	...
> 	<Types>
> 	  <Namespace Name="Test">
> 	    <Type Name="Test`1" />

To be fair, current output would be:

	<Type Name="Test`1" DisplayName="Test&lt;T&gt;" />

i.e. an added Type/@DisplayName attribute.

> 	  </Namespace>
> 	</Types>
> 	....
> 
> Test`1.xml (Note that the the filename and name of the type are already
> different):

Necessary, actually, because '<' and '>' are not valid filename
characters on Win32. :-)

> 	<Type Name="Test&lt;T&gt;" FullName="Test.Test.Test&lt;T&gt;">
> 	...
> 
> But then again it seems that the browser uses the Test&lt;T&gt;
> everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> but other times not and some ugly HTML-Entities are being shown as the
> class name.

These are bugs in the doc browser and should be fixed.

> To streamline all these naming issues my proposal is to use the Test`1
> Notation everywhere to be more coherent with the output of Type.Name and
> not to introduce too much C#-Notations into the docs since Mono can be
> used from a couple of languages.

I don't like this idea, mostly because e.g. Dictionary`2 is wildly
undescriptive.  Even Microsoft doesn't do this; instead, they do
"Dictionary Generic Class" for the .NET 2.0 docs, and (more sensibly)
"Dictionary(TKey,TValue) Generic Class" for the .NET 3.5 docs.

We could go the .NET 3.5 approach for the DisplayName attribute if you
care that much. :-)

But I really don't want to do Dictionary`2 because it's wrong.  Most
people don't know what "`2" is going to mean, it's ugly, and losing the
"TKey, TValue" part is a loss of some nice information.

> Generic Methods are also stored in the fancy "Method&lt;T&gt" way while
> the Name returned by the corresponding MethodInfo would just be
> "Method". Here I would also alter the Name to be compliant with the
> output of MethodInfo, otherwise different generic overloads won't be
> recognized as an overload (See Console.Write for example)

Generic methods use "Method&lt;T&gt;" because that's what the ECMA
documentation does.  I did this for consistency, as the monodoc XML
format is based on the ECMA XML format.

> The changes in monodocer should be pretty easy to do (probably less 20
> lines of code). However I haven't yet tested how the rest of the
> documentation stack will react. Any comments on that?

You have a point that "<" and ">" are rather C# specific, so
following .NET 3.5 and using '(' and ')' might be an acceptable
compromise (again, if you care that much; personally, I don't have a
problem with using '<' and '>').  For reasons stated above, I do NOT wnt
to use Foo`N notation in the shell.

Furthermore, since you can "overload" types based on the number of
generic type parameters, not using <>/()/[]/etc. to enclose type
parameters either results in name ambiguities (if you only show what's
before the '`', as .NET 2.0 docs do), or requires the use of `N
notation.  Consider:

	delegate R Func<R> ();
	delegate R Func<R,P> (P p);
	delegate R Func<R,P1,P2> (P1 p1, P2 p2);

Which results in Func`1, Func`2, and Func`3, vs. Func<R>, Func<R,P>, and
Func<R,P1,P2> (or replace <> with () or something else).  I find the
latter far preferable.

 - Jon