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

[Jonathan Pryor]

On Wed, 2006-10-04 at 17:28 -0400, Joshua Tauberer wrote:
> Another thing... I wonder if it would make sense to rename the index.xml
> Name and File attributes to DisplayName and Signature to make what they
> represent clearer, and, I think, because the File attribute is used not
> just for file locations but also for matching signatures in crefs.

I'm not sure DisplayName is a significant improvement over Name.  I
actually prefer the shorter names, if possible.

You make a good argument for @File, though, as it's really used for all
type matching.  I don't like Signature though, as a "signature" is
frequently used to refer to the prototype of a method, and this is
something different.

Perhaps CanonicalName?

> And the File attribute should be mandatory (i.e. inserted on update)
> since monodocs2html assumes a File attribute is present on all type nodes.

It should be easy to get monodocs2html to "fallback" to using @Name if
@File is empty or doesn't exist, so I don't find this a credible reason
to require the presence of @File.

> Also, do you know of a reason for *sticking* with +'s in nested types?
> crefs don't use +'s, right?  (A quick Google search shows someone
> reporting +'s aren't/weren't used by VS.NET, but I don't know for sure
> if that's right.)  If that's the case, it seems like things can be
> simplified if we just drop +'s everywhere.  OTOH, if we stick with +'s
> in the File attribute, we could change the conventions for crefs so they
> are easier to parse (albeit breaking from Microsoft, which isn't so bad
> actually because we can handle the difference in the /doc import/export
> tools).

I know of a good reason: I *tried* that, and it failed *dismally* when I
tried to get things working in monodoc/engine.

Simple experiment: take any monodocer-generated directory tree with a
nested type, and edit the Namespace/Outer+Inner.xml file to change:

	<Type Name="Outer+Inner" FullName="Namespace.Outer+Inner">

to

	<Type Name="Outer.Inner" FullName="Namespace.Outer.Inner">

Then edit the file within monodoc: monodoc --edit dirname

When you view the documentation for that file, instead of getting a link
for the "Namespace Namespace", you'll get a link for the
"Namespace.Outer" namespace.  This is because monodoc/engine uses
everything before the last '.' as the namespace, and everything after it
as the type name.

Furthermore, I can't think of a way to "fix" this to permit using '.' as
the nested type separator, as you can have
Any.Number.Of.Namespaces.And.Nested.Types in a full type name -- which
of those is the namespace, and which is the type?  You'd also have to
use this algorithm to determine which file to edit as well, or you'll
get exceptions when it can't find the file its looking for (or do a
*lot* of `if (File.Exists(...))' checks to find the file you're after,
effectively one File.Exists() check for each '.' in the type name).

So unfortunately, '+' needs to remain as the nested type separator char,
at least within the documentation files.  Cref's don't need to use it,
as full namespace+type traversals are used anyway (at least in
monodocs2html), so the type will still be found regardless.

 - Jon