Re: [Mono-docs-list] What to do about types in the root namespace?
Hi,
what about printing a big warning saying those classes A,B and C
won't be documented because they are not contained in a Namespace and
ignoring them when writing the documentation?
Mario
On 20/12/2007, Michael Hutchinson <[EMAIL PROTECTED]> wrote:
> On Dec 19, 2007 9:52 PM, Jonathan Pryor <[EMAIL PROTECTED]> wrote:
> > 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.
> ...
> > We could just say "Don't Do That," and be done with it. :-)
>
> Putting types in the root namespaces sounds to me like a Bad Thing,
> violating naming guidelines etc. IMO this isn't something that MonoDoc
> should care about -- if anything, it should throw an error (as it
> does) or ignore them.
>
> --
> Michael Hutchinson
> http://mjhutchinson.com
> ___
> Mono-docs-list maillist - Mono-docs-list@lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
>
___
Mono-docs-list maillist - Mono-docs-list@lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] What to do about types in the root namespace?
On Dec 19, 2007 9:52 PM, Jonathan Pryor <[EMAIL PROTECTED]> wrote:
> 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.
...
> We could just say "Don't Do That," and be done with it. :-)
Putting types in the root namespaces sounds to me like a Bad Thing,
violating naming guidelines etc. IMO this isn't something that MonoDoc
should care about -- if anything, it should throw an error (as it
does) or ignore them.
--
Michael Hutchinson
http://mjhutchinson.com
___
Mono-docs-list maillist - Mono-docs-list@lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] What to do about types in the root namespace?
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
Where should types in the root namespace be placed? As siblings of the
namespace nodes?
+ Class Library
+ System
+ Array
+ Methods
- AsReadOnly
- RootNamespaceType Class
As children of a "Global" namespace?
+ Class Library
+ System
+ Array
+ Methods
- AsReadOnly
+ 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
Re: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed generic types.
On Wed, 2007-12-19 at 19:43 +0100, Valentin Sawadski wrote: > On Wed, 2007-12-19 at 13:33 -0500, Jonathan Pryor wrote: > > I can't reproduce this. What I'm doing: > > > > 1. Navigate to System.Array.BinarySearch(T[],T). > > 2. Within the Right pane, Click the "IComparable" link above > > the prototype. > > > > I'm then taken to IComparable documentation. > > This is very strange, because it does not work at my machine (rev > 91596). Do you have any idea why it is not working for me, but for you? > (I'm not using Gecko to render the pages.) Did you update & install *both* monodoc/engine AND mono-tools/docbrowser? One of my recent fixes in monodoc/engine "fixes" "invalid" links that were present in the imported ECMA documentation, invalid links of the form "T: Namespace.Type" (note the space after the ':'). Clicking on these links would previously go to a nearly blank page containing the only text of the link you just clicked. An example of this is M:System.Array.AsReadOnly, which in the summary links to "T: System.Collections.Generic.IList " (note the space). Is it possible that the links you're clicking which lead nowhere are of this malformed type? Thanks, - Jon ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed generic types.
Hello Jonathan, On Wed, 2007-12-19 at 13:33 -0500, Jonathan Pryor wrote: > On Wed, 2007-12-19 at 18:59 +0100, Valentin Sawadski wrote: > > On Tue, 2007-12-18 at 09:31 -0500, Jonathan Pryor wrote: > > > On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote: > > > > this short patch makes all properly formatted and malformed links in the > > > > docbrowser work. Please review it and apply if no one objects. > > > > > > This isn't necessary; I "fixed" GtkHtmlHtmlRender (in > > > mono-tools/docbrowser) to do the s/ > > (since this is in my mind a GtkHtml bug, in that it isn't properly > > > rendering/un-escaping XML entities). > > > > I see your changes but they only worked for the MembersOverview page, as > > far as I can tell. > > > > See System.Array for example. If you click BinarySearch(T[], T) in > > the overview, everything works fine. When you then hover over the the > > IComparable link, the status-panel displays the right "URL" however > > if you click it, you'll end up in the middle of nowhere again. > > I can't reproduce this. What I'm doing: > > 1. Navigate to System.Array.BinarySearch(T[],T). > 2. Within the Right pane, Click the "IComparable" link above > the prototype. > > I'm then taken to IComparable documentation. This is very strange, because it does not work at my machine (rev 91596). Do you have any idea why it is not working for me, but for you? (I'm not using Gecko to render the pages.) Kind Regards, Valentin ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed generic types.
On Wed, 2007-12-19 at 18:59 +0100, Valentin Sawadski wrote: > On Tue, 2007-12-18 at 09:31 -0500, Jonathan Pryor wrote: > > On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote: > > > this short patch makes all properly formatted and malformed links in the > > > docbrowser work. Please review it and apply if no one objects. > > > > This isn't necessary; I "fixed" GtkHtmlHtmlRender (in > > mono-tools/docbrowser) to do the s/ > (since this is in my mind a GtkHtml bug, in that it isn't properly > > rendering/un-escaping XML entities). > > I see your changes but they only worked for the MembersOverview page, as > far as I can tell. > > See System.Array for example. If you click BinarySearch(T[], T) in > the overview, everything works fine. When you then hover over the the > IComparable link, the status-panel displays the right "URL" however > if you click it, you'll end up in the middle of nowhere again. I can't reproduce this. What I'm doing: 1. Navigate to System.Array.BinarySearch(T[],T). 2. Within the Right pane, Click the "IComparable" link above the prototype. I'm then taken to IComparable documentation. - Jon ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed generic types.
Hello Jonathan, On Tue, 2007-12-18 at 09:31 -0500, Jonathan Pryor wrote: > On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote: > > this short patch makes all properly formatted and malformed links in the > > docbrowser work. Please review it and apply if no one objects. > > This isn't necessary; I "fixed" GtkHtmlHtmlRender (in > mono-tools/docbrowser) to do the s/ (since this is in my mind a GtkHtml bug, in that it isn't properly > rendering/un-escaping XML entities). I see your changes but they only worked for the MembersOverview page, as far as I can tell. See System.Array for example. If you click BinarySearch(T[], T) in the overview, everything works fine. When you then hover over the the IComparable link, the status-panel displays the right "URL" however if you click it, you'll end up in the middle of nowhere again. > > I made the GtkHtmlHtmlRender change on Dec-12. > > - Jon > > Kind Regards, Valentin ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
