While trying to update the contents of monodoc/class, I ran into a
problem: Npgsql contains the following types in the root ("") namespace:
NpgsqlRowUpdatingEventArgs, and NpgsqlRowUpdatedEventArgs.
The problem is twofold:
1. monodocer generates an error and exits if it sees such a type.
2. What should Monodoc do with such a type?
Assuming that telling the Npgsql authors to rename their types is
undesirable, we need a way to support types in the root namespace.
These aren't intractable problems, but the solution isn't entirely clear
to me either.
For (1), monodoc could do one of the following (alternatives desired):
a. Place the types into a 'Global' directory, e.g.
assembly-name/en/Global/NpgsqlRowUpdatingEventArgs.xml.
Problem: what if someone actually uses a 'Global' namespace?
b. Don't care, and write the file
assembly-name/en/NpgsqlRowUpdatingEventArgs.xml (i.e. use "" as the
namespace).
This should work, as you can't have a namespace and type with the same
name within a given assembly.
HOWEVER, it's quite possible to spit the monodocer output of multiple
assemblies into the same directory; in fact, this is currently done in
monodoc/class, spitting the output of the assemblies nunit.core,
nunit.framework, nunit.mocks, and nunit.util into the nunit directory.
Consequently, if assembly A has a namespace Foo, and assembly B has a
type Foo, and you request monodocer to generate output for both
assemblies into the same directory, the Foo.xml file would be clobbered,
containing whichever assembly was most recently documented.
We could just say "Don't Do That," and be done with it. :-)
Solution (b) is my preference.
Then there's question (2), which I find harder to solve: what should
Monodoc do with these types?
Currently, the tree of monodoc assumes that all types have namespaces --
"Class Library" has namespace sub-nodes, which contain actual type
sub-nodes:
+ Class Library
+ System
+ Array
+ Methods
- AsReadOnly<T>
Where should types in the root namespace be placed? As siblings of the
namespace nodes?
+ Class Library
+ System
+ Array
+ Methods
- AsReadOnly<T>
- RootNamespaceType Class
As children of a "Global" namespace?
+ Class Library
+ System
+ Array
+ Methods
- AsReadOnly<T>
+ Global
- RootNamespaceType Class
Something else?
Note that the "parent tree" has some say over how logical the choice is.
The "Class Library", "Gnome Libraries", etc. nodes are spread across
multiple namespaces, so any type in the root namespace may be far away
from the types it should be used with.
On the other hand, the "Various" node has more subdivisions:
+ Various
+ NUnit Libraries
+ NUnit.Framework
+ Assert Class
So any types in the root namespace may be closer to the types they're
likely to be used with.
Then there's the issue of monodoc internals: iirc, many portions assume
that there is a namespace within the Fully Qualified Type Name, and use
string manipulation operations to extract the namespace. What happens
when the namespace is, rightfully, ""? I have no idea.
Thoughts?
Thanks,
- Jon
_______________________________________________
Mono-docs-list maillist - Mono-docs-list@lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
