[Mono-docs-list] using mdoc to report doc/code differences?

[Jonathan Pryor]

On Mon, 2010-01-11 at 16:32 -0800, Arne Claassen wrote:
> I've been using the inline Xml Docs for one main reason: Separate  
> documentation too often leads to documentation rot. I especially like  
> that I get warnings about missing or extra documentation members as  
> part of my build. But I have to agree that it makes the code hideous  
> and it's a less than ideal editing experience with xml inside of  
> comments.

There is an unexplored solution here: the <include/> XML doc comment:

        http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx

For example:

        /// <include file="your-docs.xml" path="//insert/xpath/here" />
        public class Example {}

What I've occasionally pondered is directly referencing the mdoc
repository, though I suspect that at present the path value would be
annoyingly complicated.  It might be possible to enhance the mdoc
repository format to more easily support this, e.g. by adding a //Cref
element which contains the cref for the type/member.  This would allow
for <include file="path/to/Example.xml" path="//Cref='T:Example'" />.

Someone should prototype this (or see if there's a straightforward way
to do this w/o extending the Type.xml format).

Doing this would allow you to keep your documentation outside of your
source, while (hopefully) still getting warnings from the compiler about
undocumented members.

Of course, there's no actual need to refer to the mdoc repo here; any
XML file can be used, with any XPath, so you could define your own
custom XML dialect to store doc comments, use <include/> to generate the
Assembly.xml file, and import those into the mdoc repository.  The
downside is this results in three different copies of your documentation
running around, hence the above suggestion to directly use the mdoc repo
comments...

> I was wondering if there is a way to call mdoc to report inconsistency  
> for a type member, so i could put mdoc update and inconsistency  
> checking into the build.

I don't understand this, actually; can you provide an example?  For
example, do you want mdoc to give a warning when importing documentation
and no documentation was found for a particular member?  Something else?

Thanks,
 - Jon