[Mono-dev] Using mdoc for internal documentation

[Jonathan Pryor]

On Mon, 2009-04-06 at 17:06 -0700, Casey Marshall wrote:
> Sometime ago, though, it looks like `monodocer' became an alias for  
> `mdoc update'. I'm having trouble getting mdoc-update to do the right  
> thing.

This happened with Mono 2.0.

> I tried this, in makefile syntax (DOC_TARGETS is a list of targets doc- 
> *, for each project in our tree, and all-* targets build each project):
> 
>    docs: $(DOC_TARGETS)
> 	mdoc assemble --out=monodoc/fish monodoc
> 
>    $(DOC_TARGETS): doc-%: all-%
> 	-mdoc update --out=monodoc --import=xmldoc/`$(shell echo $* |  
> tr / .).xml $*/bin/Debug/*.dll
> 
> This doesn't seem to work; in particular, lots of classes from the  
> assemblies are omitted.
> 
> One common error I get from `mdoc update' is:
> 
>    mdoc: Could not resolve: foo.dll, Version=XXX, Culture=neutral,  
> PublicKeyToken=XXX

I suspect that the missing classes are due to the above resolving error.

Which version of Mono are you using?  Specifically, Mono 2.4 or earlier?
In Mono 2.4 mdoc-update was changed to use Cecil, while previous
releases (and monodocer) used Reflection.  If you're running Mono 2.4
this could be a bug introduced by the migration.

Also, what is 'foo.dll'?  Is it a library that you built, or a
GAC-located assembly?  If you're using Mono 2.4, Cecil will only check
the GAC and the directories of assemblies specified on the command line.

It's possible that placing all of your assemblies into the same
directory will fix this, instead of placing them into separate
directories (e.g. build into a common bin/Debug directory, instead of
into multiple */bin/Debug directories).  If this is the case, please let
me know so that I can fix a future release (along with details of the
assembly dependencies, etc., as when I try this locally it works as
expected.)

> for various assemblies that I both specify in the assemblies list on  
> the command line, AND are in a directory listed in MONO_PATH.

Hm, this might be the problem: MONO_PATH isn't searched in Mono 2.4 (as
Cecil doesn't check it).  If you're using Mono 2.4 AND you built from
source, try applying the attached patch from mcs and rebuilding mdoc.
(The patch causes mdoc-update to add MONO_PATH directories to the
assembly search directories.)  This _may_ fix it...

> My question, then, is: what's the right way to do this -- assemble a  
> bunch of assemblies and XML documentation files into a  
> single .tree/.zip file for monodoc?

What you're doing should be working (i.e. it's a bug in mdoc).  Alas,
I'll need to figure out what the bug is in order to fix it...

Furthermore, it isn't necessary to bundle everything together in a
single set of .tree/.zip files (though it may be more convenient for
you).  Since Mono 2.4 (2.2?), the .source file format allows you to
specify "parent" nodes, which allows multiple sets of .source/.tree/.zip
files to have the same "logical" parent node.  This is currently done
with the Gendarme documentation (each assembly has its own set of files)
and with Mono.* and mono-addins-docs.*, e.g. Mono.source:

        <monodoc>
          <node label="Mono Libraries" name="classlib-mono"
            parent="libraries" />
          <source provider="ecma" basefile="Mono" path="classlib-mono"/>
        </monodoc>

and mono-addins-docs.source:

        <monodoc>
          <node label="Mono Libraries" name="classlib-mono"
            parent="libraries" />
          <source provider="ecma" basefile="mono-addins-docs" 
            path="classlib-mono"/>
        </monodoc>

If you're able to run 'mdoc-update' separately for each assembly without
error (while running 'mdoc-update' for all assemblies at once does
produce errors), then it may be an option to assemble all the docs
separately and merge them into the same tree using the .source file.
The mdoc-assemble(1) man page provides documentation for the .source
file XML.

 - Jon

-------------- next part --------------
A non-text attachment was scrubbed...
Name: mdoc-update-MONO_PATH.patch
Type: text/x-patch
Size: 1160 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-devel-list/attachments/20090406/6b05e2aa/attachment.bin