[Mono-list] Re: [Mono-hackers-list] Re: Patch for mcs

[Gaurav Vaish]

> Thanks for the explanation.
> 
> Now the question is: how is this different from the /doc switch that we
> are adding today to mcs?

   Ok. Initially there may not be any different. However, the "/doc"
switch only produces XML-doc. And to format the XML-doc, you need to
create your own xslt -- the crude way in which NDoc works.

   However, I want to give power to create any document-engine that
can work on the raw comment strings. See JavaDoc related links below.

> 
> Would it be possible to instead just use the output produced by
> mcs /doc?  My concern is that I do not want to add code to the compiler
> without having a good reason for having it there.

   No. The reason is -- it is very difficult to extend the "language"
of the doc-tool, I mean the elements understood by it.

> What are docklet and taglets?

Javadoc:
    http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/

Towards the end of the page is a separate section on "Doclets" (not APIs).

Doclet:
   http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/overview.html
Taglet:
   http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/overview.html


> So the issue is: woul d it not be best to focus our efforts on a single
> solution?  For example, adding chm support to Monodoc would be a great
> addition.

   That's fine. But then, the engine would work on the final XML that
it gets. Not an issue - NDoc works in the same manner. Has xslt to
convert XML into several HTMLs and then uses MS Help Compiler to
create CHM.

   But that's just one extension. Tomorrow we may wish to create other
extension -- working on final XML may be more than a little pain.
Parsing it each and everytime with xslt to get a single HTML... it's
pain both for me and my processor.

   Just for example, look at this:
    http://xdoclet.sourceforge.net/xdoclet/index.html

  It cannot work with the current inextensible "/doc" swtich. Where's
the power at program-level to understand new tags?

  And to do so, you need raw comments and let the "Doclet" or "Taglet"
parse the raw information if required! It's not possible to keep on
extending "/doc" switch. Let everybody create their own custom Doclet
/ Taglet. Unleash the power!!!


--
Cheers,
Gaurav Vaish
http://csdoc.sf.net
-------------------