[Mono-docs-list] The future of monodoc.dll

[Mike Kestner]

On Sat, 2008-03-22 at 09:47 -0400, Jonathan Pryor wrote:
> One of the things I'd like to do before the Mono 2.0 release is migrate
> monodoc.dll to use C# 2.0 features such as generics in the public API.
> For example, instead of Monodoc.Node.Nodes being an ArrayList, it should
> be an IEnumerable<Node> or IList<Node>, and Monodoc.Node should
> implement IComparable<Node>, etc.

I guess my main question would be, why?  It doesn't save boxing
overhead, since Node is a reference type, right?  Seems like
considerable pain to avoid typing 'as Node' occasionally.

Unless the generics usage is necessary for a feature addition to a
consumer of the dll, I don't see the justification for breaking
stability.

> However, I'm not sure that this can actually be done, as monodoc.dll is
> installed into the GAC, and such an API change would break any existing
> clients on upgrade.

In order to do it, you would need to install a new assembly version into
the GAC, and probably make a monodoc-2.0.pc which is
parallel-installable to the old version.

> Consequently, I thought I'd throw out another idea: #ifs and changing
> the assembly name.
> 
> Instead of building just monodoc.dll, we could build both monodoc.dll
> and a Mono.Documentation.dll.  monodoc.dll would remain .NET 1.0
> compatible, Mono.Documentation.dll would be for .NET 2.0, and we could
> use #if's to keep the two separate:

If we are really going to end up with two separate dlls, we probably
ought to spec out what we need for features in a new "engine" dll, and
implement them in as clean as possible a codebase.

For example, my new editor/viewer could probably benefit from an engine
node that exposes raw XML.  The current system is all about returning
html for obvious reasons.

I just don't see the real benefit in having a dual assembly setup if the
only difference between the versions is a little C# 2.0 sugar.

-- 
Mike Kestner <mkestner at novell.com>