>>> In C++ i had this "\todo text" which
>>> resulted in a list of things todo as
[quoted text clipped - 9 lines]
> XML or is it rather "every one does as one
> pleases"? Several competing standards?
Bit of both, actually. There's a baseline set of tags used by everyone and
documented in the MSDN, some of which actually come with generated
Intellisense (like <summary>) and compiler support (like <param> and
<seealso>, where the compiler will verify that you're referring to existing
parameters/types).
Then there are minor extensions like (<langword>) that are widely supported
but not exactly standardized, and finally it's always possible to just
invent your own tags for specific purposes -- like <pre> and <post> if you
want to annotate your source with pre- and postconditions.
Almost all tools out there that process XML documentation are flexible
enough to allow you to specify your own tags and how they should be
processed, so there's little competition going on, really.
> 2. Is it a good idea to go in depth with the XML commenting and adapt it
> seriously or is it rather sparely used?
Depends on what you're trying to achieve.
First of all, XML comments are just a good idea if you're writing a library,
or in general any sort of code that's going to be used by other people,
since it allows you to
- Provide good Intellisense support: see the use and purpose of a method or
enum value as you're typing;
- Add special usage notes or semantic restrictions that aren't expressible
in code;
- Specify what argument values a method accepts, the exceptions it can
throw, and under what circumstances it throws them.
And this is in addition to the standard <summary> documentation that allows
you to explain what things do in the first place. Your documentation may
actually be more extensive than what XML comments can provide (tutorials,
samples, broad overviews, etc.) but XML comments should definitely be a part.
Whether you should be creative in adding your own tags, that's another
matter. The baseline set of tags is actually pretty extensive, and there
aren't that many cases where you'd really want to add your own semantic
information (the pre- and postconditions I mentioned would be one, if you do
programming by contract). However, XML comments are flexible enough that you
can actually do this without much fuss -- if you often need to cooperate
with other developers on code that's incomplete, for example, <todo> might
come in handy.
If you just need to search on TODOs without the rest of the documentation,
on the other hand, XML comments aren't any more handy than regular comments,
unless you write your own processing tools.

Signature
J.
Lasse Vågsæther Karlsen - 24 Mar 2008 12:16 GMT
<snip>
> Then there are minor extensions like (<langword>) that are widely
> supported but not exactly standardized, and finally it's always possible
[quoted text clipped - 4 lines]
> enough to allow you to specify your own tags and how they should be
> processed, so there's little competition going on, really.
Just need to ask... are there that many tools? The two I know of are
NDoc and Sandcastle, and NDoc is dead, and Sandcastle ought to be, are
there any others?

Signature
Lasse Vågsæther Karlsen
mailto:lasse@vkarlsen.no
http://presentationmode.blogspot.com/
PGP KeyID: 0xBCDEA2E3
Jeroen Mostert - 24 Mar 2008 13:05 GMT
> <snip>
>> Then there are minor extensions like (<langword>) that are widely
[quoted text clipped - 9 lines]
> Just need to ask... are there that many tools? The two I know of are
> NDoc and Sandcastle, and NDoc is dead, and Sandcastle ought to be,
Oh, come on. It's still in the early stages. It's slow and ponderous, but it
does get the job done.
You can still use the alpha build of NDoc for .NET 2.0 if you're so
inclined, which is at least faster.
> are there any others?
Serious projects? No. The rest is all incidental stuff (and most of it died
when NDoc came around). Visual Studio .NET actually had its own rudimentary
documentation builder (Tools -> Build Comment Web Pages), but this feature
wasn't carried forward.

Signature
J.
BobF - 24 Mar 2008 14:20 GMT
Doxygen?
> <snip>
>> Then there are minor extensions like (<langword>) that are widely
[quoted text clipped - 9 lines]
> and Sandcastle, and NDoc is dead, and Sandcastle ought to be, are there
> any others?
K Viltersten - 24 Mar 2008 14:43 GMT
> Doxygen?
I'm no expert on Doxygen but when we
used it for our C++ project, the
comments needed to be like:
/** A method that is SOOO cool.
\param input parameter in
*/
and that it wasn't possible to use
XML comment system at all. Is it
still true?
--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy
K Viltersten - 24 Mar 2008 14:55 GMT
> Doxygen?
Also, have the issues with partial
classes and other minor problems
been resolved?
--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy