Re: using mdoc to report doc/code differences?

On Jan 12, 2010, at 10:20 AM, Jonathan Pryor wrote:

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

Plus the first time update runs, that "To be added" doc will be  
generated anyhow. And if i am to go external with docs, i'd rather be  
completely external.

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

Just got the source from svn, will have a look whether I can figure  
that part out.

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

For my case at least i would want the error to be on anything not  
properly documented. This is where warning instead of error would be  
nice, so it's something you will clean up before check-in, but you're  
not blocked from testing and refactoring in the meantime.

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


I can live with that as well. What I'd really like to do is create a  
visual studio extension that uses mdoc to check and generate docs,  
provide warnings that link to the code and allow the two-way  
navigation between code and doc xml by clicking in the source on  
either side. However, i can see that being a pit of quicksand, so i  
wouldn't even make any claims that i would attempt that until i have a  
prototype :)

Arne Claassen

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

_______________________________________________
Mono-docs-list maillist  -  [email protected]
http://lists.ximian.com/mailman/listinfo/mono-docs-list