[Mono-docs-list] doctools: fork in the road?
Sat, 16 Feb 2002 22:35:39 -0800
Here is the deal. I have been working diligently on all of the tools and am
ready to commit something to cvs. I've also recently taken a look at NDoc
(GPL'd ndoc.sourceforge.net) as John Barnette has suggested and this has led
to an impending decision of sorts. The NDoc stuff is very impressive, they
have been coding for quite sometime and far along. With that said, here are
the choices I see for the road ahead:
1. Continue building docstub, docgen, docconv, and monodoc. -- The Pro's
for this are: We generate our own DTD/Schema for the xml which is simpler and
it makes it easier to code the docgen tool (combining reflection metadata xml
and extern documentation). The NDoc stuff is written to combine the /doc
compiler option output of Microsoft's csc compiler with information generated
via reflection metadata. Mono's mcs does not have this feature, so a great
amount of information would be lost to us, if we just went with NDoc. The
Cons: Well, just that NDoc is farther along and it seems beneficial to
combine efforts wherever we can, which means we could also...
2. Use NDoc as our documentation tool. This would imply that we build /doc
compiler output into mcs. The Pro's for this are: We get to piggyback on
all of the work that has gone on before. The Cons are: Not sure how
trivial this would be, and I personally, don't like the look of
NDocs/Microsoft's DTD/Schema. I haven't been able to find a spec for it and
IMHO it looks like another convoluted Microsoft document format. Of course
we could just ask the nice folks at NDoc for more information, which leads to
3. We could choose to adapt/extend NDoc to combine with our external
documentation. The Pro's: Well, this way we don't have to worry about mcs
and the /doc output. The Cons: Once again, I think this would be a
nightmare because of the convoluted DTD/Schema of NDoc/Microsoft. Also, I
haven't been able ot get NDoc built either with wine or on Windows... They
only use nmake and there stuff is already heavily tied to Windows.Forms.
That is another plus for continuing on our own, command line tools, which
leads me to this...
Regardless the decision, if we decide to continue on our own, then I will be
adapting DocStub to use NDoc's backend for generating reflection metadata.
They already have this stuff figured out and it is quite frankly a lot better
than my ad hoc backend. Work on this has already begun and it is fairly
I am itching to get back to work on the Qt Bindings so I'd like to get this
all sorted out and done. Well let me know what you all think and i'll commit
to cvs as soon as I get some feedback.