The future of monodoc.dll

[Jonathan Pryor]

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.

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.

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 NET_2_0
        using NodeList = System.Collections.Generic.IList<Mono.Documentation.Node>;
        #else
        using NodeList = System.Collections.ArrayList;
        #endif
       
        public class Node : IComparable
        #if NET_2_0
          , IComparable<Node>
        #endif
        {
                public NodeList Nodes {...}
        }

This is similar/identical to what we do in mcs/class.

The alternatives are to:

1. Keep monodoc.dll as .NET 1.0 only -- no generics, etc.

2. Migrate monodoc.dll to .NET 2.0, and change the assembly version
number.  Problem is that the 1.0 monodoc.dll couldn't be built anymore
without using e.g. the monodoc-1.9.tar.gz file.

3. Keep monodoc.dll, and use a different set of source files to build
the .NET 2.0 Mono.Documentation.dll.  Perhaps it could use the 1.0
monodoc.dll as part of its implementation...?

4. Something else?

Thoughts?
 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[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@...>

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Mario Sopena Novales-2]

Hi,

   I agree with Mike. More important than C# 2.0 sintantic sugar is
all the wrong things with the current monodoc API:

* two lookup alternatives (tree node and URL based)
* not a clear render pipeline: like Mike said, it does not expose XML,
but is is also has a rather strange way of dealing with editing and
its hardly extensible
* no easy way of installing new documentation (or updated one)
* Some minor capabilities to edit documentation of a project but no
easy way to reuse the monodoc remote documentation editing
capabilities with something not the mono project documentation
* Wrong way of handling with "installed documentation". There is no
way to deal with documentation packages. Instead, you are presented
with a list of possible documentation packages, some of them could be
installed, some of them not.

Mario

On 22/03/2008, Mike Kestner <mkestner@...> wrote:

>
>  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@...>
>
>
>  _______________________________________________
>  Mono-docs-list maillist  -  Mono-docs-list@...
>  http://lists.ximian.com/mailman/listinfo/mono-docs-list
>

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Miguel de Icaza-2]

Hello,

> 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.
>
> 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.

We can consider monodoc.dll in the GAC as being an internal API, it was
never supposed to be an API set in stone, we never really advertised it,
and other than MonoDevelop, I do not believe there are many users of it.

So I would not sweat too much about it.

> 4. Something else?

This one ;-)

Its an internal API, lets just move ahead.

> Thoughts?
>  - Jon
>
>
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list@...
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Miguel de Icaza-2]

> * no easy way of installing new documentation (or updated one)

Yes, there is an easy way.   Drop in the new files.

The only thing we have not made is easy is to modify the tree, but that
was done on purpose, so we would get third-parties always under
"various".

We can revisit this decision if its important.

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list