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

[Mario Sopena Novales]

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