[Mono-dev] Using mdoc for internal documentation

[Casey Marshall]

On Apr 9, 2009, at 2:20 PM, Jonathan Pryor wrote:

> On Thu, 2009-04-09 at 12:56 -0700, Casey Marshall wrote:
>> Nope. At least, it doesn't if I run monodoc like this:
>>
>>   mdoc update --out=generated-docs --import=xmldoc/bar.xml
>> bin/Debug/bar.dll
>>
>> ...and don't specify all the .dlls that foo.dll links to on the
>> command line.
>
> That should still cause problems anyway, though, as in some contexts
> mdoc _needs_ the other assemblies, and it won't be able to find them  
> (as
> you're not listing them all).
>
> For example:
>
> 	// assembly A.dll
> 	class Base<TKey, TValue> ...
>
> 	// assembly B.dll
> 	class Derived : Base<string, string> ...
>
> The resulting Derived.xml file will contain:
>
>  <Base>
>    <BaseTypeName>Base&lt;System.String,System.String&gt;</ 
> BaseTypeName>
>    <BaseTypeArguments>
>      <BaseTypeArgument TypeParamName="TKey">System.String</ 
> BaseTypeArgument>
>      <BaseTypeArgument TypeParamName="TValue">System.String</ 
> BaseTypeArgument>
>    </BaseTypeArguments>
>  </Base>
>
> However, mdoc can't determine the TypeParamName values without looking
> up the Base<TKey,TValue> type, and if you don't specify all assemblies
> then it won't be able to find it...
>

I don't think I've run into that, but point taken.

> It sounds like mdoc needs to support a -r:ASSEMBLY argument (or
> -lib:PATH), to reference assemblies (for later lookup) but NOT  
> document
> them, thus assisting these cross-assembly dependencies.
>

+1 for that idea!

>> From my understanding of things, the patch wouldn't fix
>> this, since an assembly could still get constructed outside the  
>> method
>> modified there, and thus with a default resolver instance.
>
> Indeed, yet another thing that hadn't occurred to me. :-(
>
>> If I add all the assemblies involved to the command line, I get
>> undocumented entries for all the members of those assemblies, since
>> I'm not giving any --import options for their XML doc files. So, I'd
>> rather not do it that way.
>
> As an aside, it should be possible to merge all the XML from your
> various assemblies and then import them all at once...but I don't know
> of any automated way to do this, so constructing the merged XML  
> would be
> a manual process (and thus not ideal).
>
> That said, I'm not sure it actually matters.  Sure, for the *first*
> import, you'll get "To be added" members, but you can import multiple
> times, e.g.
>
> 	ASSEMBLIES = A/bin/Debug/A.dll B/bin/Debug/B.dll # ...
> 	XML_DOCS = $(ASSEMBLIES:.dll=.xml)
>
> 	for doc in $(XML_DOCS) ; do \
> 	  mdoc update -o generated-docs -i $$doc $(ASSEMBLIES) ; \
> 	done
>
> So (unfortunately from a performance perspective) you're still  
> importing
> all the assemblies multiple times, but you won't lose anything in
> subsequent updates, and you'll import all the documentation you have.
> This would also allow mdoc to find all the needed assemblies...
>

That's not ideal for me, since with our build system it gets kind of  
hard to do things on a global level like that.

> (The downside to this, which -r would fix, is that there are some
> assemblies you depend upon but don't wish to document, e.g. libraries
> that come from a third party.  So for this reason supporting -r  
> would be
> beneficial.)
>
>> I applied the attached patch, and it seems to fix this for me. This  
>> is
>> probably wrong for various reasons, but it helps me get docs
>> generated. What the patch does is use the idea of a static
>> DefaultAssemblyResolver, and it falls back to that one if
>> `type.Module.Assembly.Resolver' didn't look up the type successfully
>> in DocUtils.GetTypeDefinition.
>
> I find it similar to mine, actually, except for the added support for

Yup, the patch you posted was my starting point.

> assembly lookup in DocUtils.GetTypeDefinition() -- good catch, that --
> but I'm still not certain that this is the best way.  Even with this
> patch, it can't find all required assemblies in all circumstances (and
> thus will return `null'), which would result in a loss of  
> functionality
> in certain corner cases (such as with Base<TKey,TValue>, above).
>

I haven't tried this, but returning null might be preferable to  
letting the exception go, since the latter stops the program, leaving  
the assembly half-documented.

> Do you think a -r or -lib option would work for you (or the "multiple
> import" workaround suggested above)?
>

-r and -lib options (both of them ;-) would be best. That's kind of  
what I was half-ass-attempting in the patch I posted: essentially to  
make an implicit `-lib' argument, with the directory of the assembly  
you specify on the command line.

Thanks.