[Mono-dev] Using mdoc for internal documentation

[Jonathan Pryor]

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

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.

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

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

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

Thanks,
 - Jon