[Mono-docs-list] using mdoc to report doc/code differences?
jonpryor at vt.edu
Tue Jan 12 13:20:43 EST 2010
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 .
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.
 Famous Last Words.
More information about the Mono-docs-list