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

[Arne Claassen]

Jon,

In the ideal scenario, the documentation would live entirely in the  
mdoc repository, but doing a build would still give me the same  
documentation warnings i get with Xml document comments.

A useful intermediate step would be if i could put mdoc update into  
the postbuild and have an option to report failure if an extra member  
exists in the docs or if a member in the docs only has the default  
content and spit those warnings into STDERR, so that it breaks the  
build (i'd rather have warnings, but i don't think Visual Studio  
postbuild can generate warnings).

If the facility for that kind of error checking and reporting were in  
mdoc, I could try and build a visual studio add-in that runs the  
generation and does warning generation at build instead of using post- 
build shell commands.

cheers,
Arne Claassen

MindTouch
San Diego, CA
http://twitter.com/sdether

On Jan 12, 2010, at 8:14 AM, Jonathan Pryor wrote:

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