Generics Support for monodoc/tools

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;">...&
lt;/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!

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

Generics Support for monodoc/tools

Thread: Generics Support for monodoc/tools