[Mono-docs-list] using mdoc to report doc/code differences?
arnec at mindtouch.com
Tue Jan 12 13:57:54 EST 2010
On Jan 12, 2010, at 10:20 AM, Jonathan Pryor wrote:
> Of course, this is ~trivially "subverted" -- the <include/> could
> to documentation which just says "To be added", which isn't very
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
>> 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
> generate a warning/error on STDERR. This should be easy to add .
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
> 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
> + member (which should be enough to get to the problematic member),
> 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
San Diego, CA
More information about the Mono-docs-list