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

[Jonathan Pryor]

On Tue, 2010-01-12 at 09:02 -0800, Arne Claassen wrote:
> 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.

I *think* -- but have not tested or verified -- that using the
<include/> doc comment in your sources (and having the <include/>
comment refer to mdoc repo comments) would permit this.  Documentation
would remain in the mdoc repository, but you'd get a warning for all
members that lacked a <include/> element.

Of course, this is ~trivially "subverted" -- the <include/> could refer
to documentation which just says "To be added", which isn't very useful.

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

So if there's a member that has 'To be added' as the value, mdoc should
generate a warning/error on STDERR.  This should be easy to add [0].

However, what should the semantics be?  *All* elements shouldn't have
'To be added', or can some have it, etc.

Another problem (which can't be solved) is that, even if we do print out
a warning (e.g. print out the //MemberSignature[Language='C#'] value),
we can't map this to a source code line number.  We can provide the type
+ member (which should be enough to get to the problematic member), but
not line numbers.

 - Jon

[0] Famous Last Words.