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

Valentin Sawadski valentin.sawadski at gmx.de
Mon Dec 10 12:12:40 EST 2007


On Sat, 2007-12-08 at 11:03 -0500, Jonathan Pryor wrote: 
> 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.

This is right for the way a user sees this.

However I was also thinking of the name inside the xml-File and I
believe that it would be better to use the `N variant within the
xml-File because this would prevent the "&lgt;"-Parsing or bugs ins the
class browser and it's probably also better for the commandline-version
of the doc browser to type System.Collections.Generic.Dictionary`2 then
System.Collections.Generic.Dictionary<TKey, TValue>.

But it's true that Dictionary<TKey, TValue> is nicer to see for a
(C#)-user of the documentation.

Kind Regards,
Valentin Sawadski

More information about the Mono-docs-list mailing list