Generics Support for monodoc/tools

Attached 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 also 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

Hey, Jon.

Very nice.

I won't have a chance to look at the patch for a few days
but I had two
comments:

> 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.

I don't see how that helps, since the full file path is
Namespace/Outer+Inner.xml --- which means it already needs
to know which
period ends the namespace so it knows which directory has
the file, and
if it knows that, then it knows the next period must be a
nested class
period.

> (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!)

Fun, eh?

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man.
You're
about to have a truth-mitzvah."  -- The Colbert Report
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-listlists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list

On Sun, 2006-10-01 at 07:24 -0400, Joshua Tauberer wrote:
> Hey, Jon.
> 
> Very nice.
> 
> I won't have a chance to look at the patch for a few
days but I had two
> comments:
> 
> > 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.
> 
> I don't see how that helps, since the full file path is
> Namespace/Outer+Inner.xml --- which means it already
needs to know which
> period ends the namespace so it knows which directory
has the file, and
> if it knows that, then it knows the next period must be
a nested class
> period.

The problem is stylesheet.xsl:GetLinkTarget().  When called
with a
typename of Mono.DocTest.Generic.MyList`1.Helper`2, it
passes this to
the XSLT expression:

	<xsl:variable name="typeentry"
select="document('index.xml')/Overview/Types/Namespace/
Type[concat(parent::Namespace/Name,'.',File) =
$type]"/>

If I use `+' as the outer+inner type separator, this will
always fail,
as there will be no File attribute with a value of
"MyList`1.Helper`2",
it will instead be "MyList`2+Helper`2".

So to use "+", I'd need to find a way to translate
the '.' into a '+'
for the correct subset of the string.

Thinking about it, I've found a workaround: translating '+'
to '.' in
the select expression above allows things to work:

	<xsl:variable name="typeentry"
select="document('index.xml')/Overview/Types/Namespace/
Type[concat(parent::Namespace/Name,'.',translate(File,
'+', '.')) = $type]"/>

As this will convert the File MyList`1+Helper`2 into
MyList`1.Helper`2,
which will match the type name.

I'll include this change in the next patch submission, so
there won't be
any breaking change anymore.

Alas, I have found one other problem:
stylesheet.xsl:GetParameterType()
is broken when it needs to replace multiple type parameters;
an added
testcase for DocTest.cs:Mono.DocTest.UseLists:

  public void UseHelper<T,U,V>
(Generic.MyList<T>.Helper<U,V> helper) {}

results in a `cref' of:

M:Mono.DocTest.UseLists.UseHelper`3(Mono.Docest.Generic.MyLi
st{``0}.Helper{U,V}Mono.DocTest.Generic.MyList.Helper{``1
,V}Mono.DocTest.Generic.MyList.Helper{U,``2})

Which is just hilariously wrong.  It should be:

M:Mono.DocTest.UseLists.UseHelper`3(Mono.DocTest.Generic.MyL
ist{``0}.Helper{``1,``2})

I'm working on it, but the lack of modifiable variables in
XSLT is
driving me nuts.  The problem is that I need to replace each
parameter
type "in-order" (to get the correct ``N
replacement text), but I need to
find a way to use the output of the last
GetEscapedParameter() call to
use in the next one.

 - Jon


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

Hey,

   [ Mike, read below ]

> Permission to commit? [0]

In my opinion, this is fine to commit.

The one issue that we might have to deal with is renaming
any nested
classes on SVN, so that the documentation compiler picks the
right
things.  When you commit this, can you do this as well?

Another issue that we must keep in mind, is version
information on the
documentation.   Mike Kestner has done something like this
in Gtk# to
flag which APIs appeared when.   

I think we need a way for monodocer to be told "When
updating, flag any
new members with the "<since version="assembly
2.0/>" and also have a
mechanism that ignores nodes that have a "since
..." node when updating
an existing assembly.

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