Quote Originally Posted by Evil_Giraffe View Post
@Joacim: Yes, I know the difference between XMLDoc comments and normal comments. I'm instead questioning why you would need additional information in those documents beyond what you can extract from the code itself?

The answer, of course, is because your API is not sufficiently self documenting.

Again, show an example of a method you think needs such additional detail, and I'll attempt to disprove it.
And yet, how many times do we tell someone to go read the manual, specifically MSDN... which is documentation generated through that very same process.

Thinking about the recordset.open method for a moment... it's got a number of parameters... they are arguably named correctly... and I can set them based on that... BUT, there are some combinations of settings which may or may not produce the results I want. THAT is where the API documentation comes in handy. It isn't about knowing that such and such parameter should be a 3, but rather that when that 3 is combined with the 1 of another parameter and the "Z" of yet another, that will prevent me from editing the data in the manner I want.

-tg