|
PJ Arends wrote:
Formatting comments for XML or Doxygen or any other format just makes the comments a lot harder to read in the actual source code files. The comments in the source files should be in plain text for readability, if you want to generate seperate documentation, it should be just that, seperate!
I felt that way too until I started working with doxygen. After reading the docs for doxygen I realized that it is possible to write readable comments in doxygen format, but that most programmers who use it don't bother to try.. in keeping with most programmers' disinterest in writing comments and readable code in the first place!
|
|
|
|
|
I agree.
As code goes, XML is pretty easy to read. But if i wanted to read code, i wouldn't be wasting time on the comment block at all!
So here's the deal: i'll write XML comments when a version of VS defaults to displaying them with the tags stripped out (or rendered in a visually-pleasing manner). After all, if i wanted to start a browser to read the docs for my own code, i'd write them in a Wiki and skip the XML stuff completely.
You must be careful in the forest
Broken glass and rusty nails
If you're to bring back something for us
I have bullets for sale...
|
|
|
|
|
but I also provide everything including fully formatted remarks, examples and exception tags sometimes, especially when I add a Class/Function to our Company Library.
With NDoc you can create really nice Documentation out of the XML Comments.
Greets
Roland
Wenn der Computer wirklich alles kann, dann kann er mich mal kreuzweise.
(Manfred Schmidt)
Follow your Euro notes in their tracks
|
|
|
|
|
I am exactly the same. Most internal stuff will only get the basic level of comments (with references, I am big on those) but anything that is public or that is sufficiently complex to require examples or exceptions will get extra levels added as necessary.
I too use NDoc - I love it!
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
Yes, NDoc does rock...
BUT, I have noticed (just last night) that it is not recognising any summary comments on my Namespaces.
If I add the Namespace summary from within NDoc it is fine but the ones in my code are not being used.
George Carlin wrote:
"Don't sweat the petty things, and don't pet the sweaty things."
Jörgen Sigvardsson wrote:
If the physicists find a universal theory describing the laws of universe, I'm sure the a**hole constant will be an integral part of that theory.
My Blog[^]
|
|
|
|
|
That is an XML comments shortfall, not an NDoc one - the comments on a namespace aren't carried into the comments.xml file because namespaces themselves aren't represented. NDoc allow you to simulate what you want by having a class named NamespaceDoc in each namespace, and it will use the comments from that for the namespace and ignore the fake class. You can use #if...#endif to exclude the class from non-doc builds.
It's not perfect, but it's an option.
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
It's kind of scary that 'comments' can have a shortall. Mostly I thought the source code was supposed to be responsible for that 
|
|
|
|
|
The point of XML comments is not to comment your code - you'd just use normal comments were necessary for that - it's to describe it. People reading documentation generated by NDoc, etc, typically don't have the source code available to them to study any more than we have the .NET Framework code when we come to use its classes.
Die Freiheit spielt auf allen Geigen
|
|
|
|
|
Ah, that makes sense. Thanks! 
It also backs up my assumption that i have absolutely no use for such a thing...
You must be careful in the forest
Broken glass and rusty nails
If you're to bring back something for us
I have bullets for sale...
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
