[Mono-docs-list] Proposing a new documentation subsystem
valentin.sawadski at gmx.de
Sat Nov 24 10:16:31 EST 2007
On Sat, 2007-11-24 at 08:14 -0500, Joshua Tauberer wrote:
> I think you're making it too complicated:
> > - Insufficient support for "Multi-Version" files (e.g. Class-Libs
> > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does
> > not work if a member is only available in 1.1 and not in 2.0.
> This just requires the addition of more tags to the documentation, one
> that says when a member was removed.
I don't like that idea because this might introduce some since x,
removed in y, reintroduced in z.... patterns (Yes I know it is unlikely
but still possible)
> > - Automated user-contributions do not work properly (I don't know if a
> > contribution has ever made it into the documentation).
> The current system isn't bad fundamentally. I think there's just some
> personal overhead involved in Miguel taking the contributions and
> applying them.
Is he still the only one in charge of the documentation approval?
> > - Documentation work-cycle is pretty complicated. It is very unhandy to
> > run many tools to do one simple task. (monodoc, browser, mdassembler)
Compared to the MS world it is really more complicated on mono. A simple
"/doc" compiler flag and running nDoc would suffice on windows.
> My two cents if you really want to address some of these things would be
> to start on the UI side and make something that works "properly" with a
> plain ZIP file of the XML documentation files, and no changes on the
> server or mdassembler side. Once that works, if you need to cache some
> indexes or whatever to be able to get to pages quickly, or if you need
> changes to the XML documentation format, then look into that. A
> documentation browser should be a simple program at its core.
Yes you are right the documentation browser should be as slim as
possible. However I still do think that the current xml-only approach
does not work sufficiently because of the limitations mentioned in my
first mail. A small database back-end could provide a lot more
opportunities for the creation and maintenance of documentation.
More information about the Mono-docs-list