[Mono-list] Documentation tool

[Joshua Tauberer]

Sijmen Mulder wrote:
> As what I heard on IRC, I am not the only one that dislikes in-code
> comments.

You said it!

> But, are there any .NET classes that are designed specifically to
> read/write the XML doc files? If so, how are they called, and how well
> are they supported in Mono?

In fact, yes.  Well, there are tools to do it.  Not publicly usable 
classes, though.

   1) Monodoc can now be used to edit the text of XML documentation 
files.  (i.e. ECMA-style documentation files... we need a new name for this)
   2) Monodocer can be used to create (stub) XML documentation files and 
update documentation files based on reflection of an assembly.

A few days ago I (finally) checked in some changes to Monodoc to allow 
editing of the XML doc files directly.  (I say finally because I did the 
programming back around May and then left it untouched for the summer.) 
  With the current CVS Monodoc (in the monodoc CVS module's browser 
directory), run:

mono browser.exe --local-edit path-to-docfiles

You could, for example, run:

mono browser.exe --local-edit ../class/corlib/en

to edit the corlib docs that you would have already checked out of CVS.

There is a catch, though.  You'll need to run Monodocer on docs checked 
out of CVS because they're missing the "index.xml" file that I 
(unilaterally) thought would be a good idea for documented assemblies to 
have.  To do this, go into the /monodoc/tools directory, run make, and 
then run:

mono monodocer.exe --update --assembly mscorlib --source ../class/corlib/en

But, if you use Monodocer to create the documentation to begin with, 
you'll already have your docs ready to be edited with Monodoc.  ex:

mono monodocer.exe --stub --assembly YourAssemblyName --dest path-to-docs

If YourAssemblyName isn't in the GAC or MONO_PATH, specify an extra 
argument:

   --load path/to/assembly.dll

so Monodocer can find the assembly.

My goal was for Monodoc and Monodocer together to (eventually) be a 
complete solution for documenting assemblies.  It's slowly getting 
there.  (I'm not sure if Miguel particularly wanted that, though. :) )

(BTW, your comments on the process are welcome, as would be help with 
improving Monodoc/Monodocer and also Monodocs2html.)

-- 
- Joshua Tauberer

http://taubz.for.net

** Nothing Unreal Exists **