[Mono-docs-list] [PATCH] Generics Support for monodoc/tools

[Jonathan Pryor]

At the URL below is a patch to monodoc/tools to add support for Generics
to monodocer.exe and monodocs2html.exe.  (Next stop: adding support for
Generics to the documentation browser.)

The patch is available at:

        http://balthasar.jprl.com/~jon/tmp/monodoc-tools.patch

The monodocer.cs patch is fairly straightforward in concept, if not in
implementation: Don't use Type.FullName, *ever*, as Type.FullName is
generally not what you want.  It also leads to NullReferenceExceptions
when parsing generic classes (e.g. `class Foo<T> {}').

Monodocer.exe now generates Namespace/Typename`NumArgs.xml files for all
generic types, e.g. Mono.DocTest.Generic/MyList`2.xml.  Because the
filenames for generic types will never match the C# typename
(MyList<A,B>), I've added a new File attribute into index.xml.  (If you
don't like this, it should be possible to get the "escaped" MyList`2
form from the MyList<A,B> form, but this is easiest.)

XML generated is in the same spirit as the XML Documentation from
ECMA-335 3rd edition CLILibraryTypes.xml.  So generic members have <...>
in the method name, e.g.

        <Member MemberName="SomeMethod&lt;A,B&gt;">...</Member>

As an "extension" to CLILibraryTypes.xml, <typeparam/> elements are
inserted for each type parameter.  This is in keeping with ECMA-334 3rd
edition, which suggests this tag for documenting type parameters.  (Not
sure why CLILibraryTypes.xml didn't use it.)

The one breaking change to monodocer.exe is that '+' is no longer used
for nested types, but '.' is used instead.  That is:

        public class Outer { public class Inner {}}

generates the file Outer.Inner.xml, while as before it would generate
Outer+Inner.xml.  This change is necessary for monodocs2html.exe, as
there is no way from a <see cref="T:Namespace.Outer.Inner" /> reference
to tell which of those strings is the namespace, the outer class, and
the inner class (at least, no easy way that I can see), so removing the
'+' makes monodocs2html.exe easier to implement.

The monodocs2html.exe changes include the changes I previously sent to
this mailing list, and includes an overhaul for supporting generic types
and members.  It also follows some of the conventions used on MSDN, so
"Class" follows classes, "Method" follows methods, "Generic" is inserted
for generic types and methods, etc.

(It also is ugly-as-sin, containing joyfully recursive XSLT calls to
convert "Foo<A,B>.Nested<C>" into "Foo`2.Nested`1" constructs.  Lots of
fun.  Really.  Stop looking at me like that!)

I've also added unit tests to test both monodocer.exe &
monodocs2html.exe, and has the added benefit that you can see what the
output from these tools looks like without needing to run it first.

Permission to commit? [0]

 - Jon

[0] No, I don't mean permission to commit me to an asylum for all those
recursive XSLT templates!  Recursion is fun!