Re: Differences between generic names in the documentation.

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

To elaborate further, Microsoft documentation for .NET 3.5 uses
parenthesis to enclose type parameters (as already mentioned).

The next issue, if you want a "truly" language-agnostic description, is
the Members view of a given class, e.g. Class Library -> System -> Array
-> Members.  Monodoc currently shows all type parameters AND the full
parameter list, e.g. AsReadOnly<T>(T[]), while .NET 3.5 shows only the
method name and type parameters, e.g. AsReadOnly(T).

The "advantage" to the .NET approach is a more language-agnostic display
-- no language uses (T) for type parameters, though it *is* close to
VB.NET which would use (Of T).

The disadvantage is that .NET doesn't show argument lists.  Perhaps this
isn't necessary, but I find that this leads to extra clicks within
msdn2.microsoft.com as they "collapse" all overloads into a single link.

This "collapsing" doesn't help though; see:

http://msdn2.microsoft.com/en-us/library/system.array.binarysearch(VS.90).aspx

When you view the overloads, you see _all_ overloads for a given method,
*plus* type parameters, resulting in such "helpful" language-agnostic
prototypes as:

	BinarySearch(T)([], T)
	BinarySearch(T)([], T, IComparer(T))
	BinarySearch(T)([], Int32, T, IComparer(T))

In short, I prefer the current monodoc Members view.

Given that, what's a decent language-agnostics way to show class members
AND method prototypes?  If we follow the .NET 3.5 () lead, we'd get
AsReadOnly(T)(T[]), which really helps no one.

So we either pick a language, e.g. C# (as we currently do), generating
AsReadOnly<T>(T[]), or we pick some other set of "enclosing" characters
to contain type parameters, e.g. (requires UTF-8):

	AsReadOnly「T」(T[]) : ReadOnlyCollection「T」

(using U+300C and U+300D to "quote" the type parameters), or maybe
re-use [] (I believe Nemerle does this):

	AsReadOnly[T](T[]) : ReadOnlyCollection[T]

In short, we have a trade-off between a more useful (as far as I'm
concerned) "show all overloads in the Members page" AND use a sensible
set of characters to distinguish between type paramters and actual
parameters, vs. a more language-agnostic "only show the Member name, and
display overloads in a separate page," and in the separate page use ()
to enclose *both* type parameters AND method parameters.

 - Jon


_______________________________________________
Mono-docs-list maillist  -  [email protected]
http://lists.ximian.com/mailman/listinfo/mono-docs-list