[Mono-docs-list] Differences between generic names in the documentation.
jonpryor at vt.edu
Sun Dec 9 18:27:05 EST 2007
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:
When you view the overloads, you see _all_ overloads for a given method,
*plus* type parameters, resulting in such "helpful" language-agnostic
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.
More information about the Mono-docs-list