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

[Jonathan Pryor]

On Tue, 2006-10-03 at 07:59 -0400, Joshua Tauberer wrote:
> Jonathan Pryor wrote:
> >> 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.)

Looks like I should have tried to get monodoc/engine finished before
sending this patch, as it requires using '+' instead of '.' to separate
nested types.  (Thinking about it, there's no other way to determine the
namespace, so Some.Namespace.OuterType.InnterType becomes very ambiguous
to process, e.g. for namespace determination, as the `monodoc' browser
does.)

Fortunately, I've have a monodoc/engine patch (which needs to be cleaned
up).

Unfortunately, this changes things around for monodocs2html.exe.

<Sigh.>

> Comments for the monodocer part of the patch:
> 
> After running it on some of my docs, I get these unexpected changes:
> 
> -        <ReturnType>SemWeb.N3Writer+Formats</ReturnType>
> +        <ReturnType>SemWeb.N3Writer.Formats</ReturnType>
> 
> (I'm not necessarily opposed to such a change, but I thought that was
> part of what was undone about "+" vs ".".)

The original reason for the "+" ->  "." change was for C# syntax use --
the <XxxSignature Language="C#" ...> should be in C#, so it should use
'.' to separate outer/inner types, but '+' was used instead, so I
changed this.

Obviously, that was a bad change.

> - <Parameter Name="prefix" Type="System.String&amp;" RefType="out" />
> + <Parameter Name="prefix" Type="System.String&amp;" RefType="out">
> +  <Attributes>
> +   <Attribute>
> +    <AttributeName>System.Runtime.InteropServices.Out</AttributeName>
> +   </Attribute>
> +  </Attributes>
> + </Parameter>
> 
> Is "out" exposed differently through reflection in 2.0?  I think we
> should suppress this attribute, since it duplicates RefType.

.NET 2.0 "synthesizes" non-custom attributes so that you can use
Reflection to retrieve the custom attributes.  Very useful for getting
DllImportAttribute information at runtime.

However, it looks like I should keep this attribute from being
displayed.

> Also (but this is related to the +/. thing), during an update the
> index.xml file was updated by adding entries like:
> 
>   <Type Name="Sparql.QueryType" File="Sparql+QueryType" />
> 
> but without removing the old entry with the "+" in the name.

This won't be an issue in the future, since I'll have to revert to the
previous syntax anyway (discussed above).

> Lastly, the File attribute wasn't added to any existing entries in
> index.xml when doing a doc update.

IIRC, that's because the File attribute is only generated when the
index.xml file is being created, not during an update (if the filename
doesn't change).  This shouldn't be an issue, as the monodoc code checks
for filenames matching both the @Name and @File attributes, but it's
possible I'm not fully consistent here.

 - Jon