[Monodevelop-devel] XML Doc Comments in MD Source

[Michael Hutchinson]

I've been wondering whether we should re-evaluate our policy regarding
XML doc comments in MonoDevelop source. I would argue that we should
use doc comments in MD for a number of reasons. MD is a very different
case to the Mono classlibs -- the MD APIs are often only well
understood by the person who writes them, there are no alternative
sources of documentation, and the API is less stable.

For these reason, I think it is important to lower the barrier as much
as possible for getting docs from the people who are creating and
changing the APIs, so that we can improve the sorry state of our
documentation with minimal effort.

Mono policy has always been to use MonoDoc for doc comments. However,
although MD has some MonoDoc docs set up in the makefiles, these docs
are not maintained because it is *extremely* awkward to update them
when the APIs change. This is not set up -- nor is it easy to set up
-- for addins that are not in main. Nor can these docs easily be
edited alongside the code. In addition, MonoDoc docs show up in
tooltips for the current installed MD, not the MD codebase that is
being edited. These problems could be solved with a few weeks' work on
a MonoDoc generating/editing addin for MD and some hacking on MonoDoc
to allow it to include non-installed sources, but I don't think we can
easily justify that right now.

There are also other benefits:
* Tooltips would show live documentation for the current codebase
* MonoDevelop has code completion for creating XML doc comments
* Doc writing and editing would easily be accessible from the IDE on
all platforms - there is no MonoDoc editor on Mac & Windows
* Doc tooltips would work in VS
* Contributions often include doc comments, which we currently discard

It would be pretty easy to migrate the doc comments automatically back
out of MD source into MonoDoc if/when we have a decent MonoDoc addin.

I would however suggest that we have a policy to avoid clogging up the
codebase with doc comments for private/internal API and
trivial/obvious/useless documentation such as <param name="count">The
number of items</param>. I still think doc comments are ugly, I just
think that their advantages for us outweigh the disadvantages :-)

-- 
Michael Hutchinson
http://mjhutchinson.com