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

[Jonathan Pryor]

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,'.', at 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.MyList{``0}.Helper{U,V}Mono.DocTest.Generic.MyList{T}.Helper{``1,V}Mono.DocTest.Generic.MyList{T}.Helper{U,``2})

Which is just hilariously wrong.  It should be:

M:Mono.DocTest.UseLists.UseHelper`3(Mono.DocTest.Generic.MyList{``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