[Mono-dev] Using mdoc for internal documentation
casey.s.marshall at gmail.com
Thu Apr 9 18:19:12 EDT 2009
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
>> ...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
> 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:
> <BaseTypeArgument TypeParamName="TKey">System.String</
> <BaseTypeArgument TypeParamName="TValue">System.String</
> 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
> 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
>> 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) ; \
> So (unfortunately from a performance perspective) you're still
> 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
>> I applied the attached patch, and it seems to fix this for me. This
>> 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
> 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.
More information about the Mono-devel-list