[Mono-dev] Using mdoc for internal documentation

[Casey Marshall]

On Apr 6, 2009, at 8:56 PM, Jonathan Pryor wrote:

> 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.
>

I'm using mono 2.4.

> 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.
>

`foo.dll' is an assembly I've built (forgive the obfuscation). It's  
typically a very "core" assembly, i.e., one very high up in the  
dependency tree, and most certainly is in the same directory as the  
assembly depending on it, and is being specified on the command line.

In fact, I was really surprised that it was complaining about not  
finding that assembly, since it is such a central one.

> 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...
>

Another common thing I'll see is this, using `mdoc update':

   mdoc: The node to be removed is not a child of this node.
   See `mdoc help' for more information.

There doesn't seem to be any way to tell mdoc to print internal  
exceptions, and `mdoc help' isn't so helpful in this case.

> 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.
>

Nice! It was annoying that I had to try to make a single big blob of  
stuff; will cross-links among different assemblies still work, if  
things are broken up into separate tree/zip/source files?

I'll try breaking things down into smaller runs, and see if the output  
is acceptable.

Thanks!

> - Jon
>
> <mdoc-update-MONO_PATH.patch>