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

[Jonathan Pryor]

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

Yes, and no.

In some contexts, the `N variant is already used, in particular in
index.xml //Type/@Name uses the `N variant.

Then there's the individual Type.xml files, which is more problematic,
for two reasons:

 1. I'm trying to maintain compatibility with the CLILibraryTypes.xml
    document included with ECMA-335.  This permits easier importing of
    the standardized documentation whenever it changes, and this 
    documentation format does not use `N.

    This impacts e.g. //ReturnType and //Parameter/@Type, among 
    other internal elements.

 2. Many non-`N uses will be due to user-generated comments, 
    e.g. under //Docs, in particular for the //see/@cref attribute.
    The construction of this value is documented in ECMA-334 (C#
    Standard) Annex E (Documentation Comments):

        The cref attribute can be attached to any tag to provide a
        reference to a code element....   For code elements that contain
        code that uses generics, the normal generics syntax, for
        instance List<T>, cannot be used because it produces invalid
        XML.  Instead, curly brraces can be used, such as <see
        cref="List{T}"/>, or the normal XML escape syntax &lt; and &gt;
        for instance as in List&lt;T&gt;.

(2) is particularly important, not just because it's ALSO used in the
imported ECMA docs, but also because `monodocer -importslashdoc` imports
`CSC /doc`-formatted files (e.g. for 3rd party documentation).

So what you want to do -- simplify the XML contents so to minimize the
docbrowser parsing "burden" -- simply isn't acceptable.  Requiring it
would either require "munging" all of these references on import, or
kill the current import functionality.

Munging in import also won't fix any instances where people manually
edit the XML files (as I frequently do), and the ability to "fully
reference" generic types is quite helpful in documentation; consider:

        public class Dictionary<TKey,TValue> {
            /// <returns>A <see cref="IEnumerable{TKey}"/>.</returns>
                public IEnumerable<TKey> Keys {get {return null;} }
        }

In this case, it's "nice" to see IEnumerable{TKey} as the link instead
of IEnumerable`1 to help reinforce the specialization of this generic
type.

 - Jon