Re: Problems Handling Errors Correctly

"Jonathan Wood" <jwood@xxxxxxxxxxxxxxxx> wrote in message news:Ocbnj7L%23HHA.1416@xxxxxxxxxxxxxxxxxxxxxxx
Peter,

I agree that the .NET docs can be overly sparse in some cases. Many, even. But as with your observation about the .NET Framework itself, to some extent this is a consequence of the sheer size of the Framework. One hopes that over time, the documentation will get filled in, but it's not hard to see why some things may have been considered lower priority and receive a basic "template" documentation rather than a fully useful description.

Makes me wonder if the existing documentation is based on the <summary> tags in the source code. That would explain why they seem to be terse and very slow to get updated.

The class documentation is (mostly) generated from code comments - I don't remember the web site off hand but Google "SandCastle help generator" and you'll find a utility that turns the xml file generated from the code comments into MSDN style documentation (it is a public version of Microsoft's tool they use to generate alot of the class documentation)

My experience has been that possible exceptions are well-documented within the method (I can't think of any properties that throw exceptions off the top of my head, but I would expect any that do to follow the same pattern). Specifically, the docs include a section immediately after the "Return Value" section enumerating possible exceptions.

If that is the case, and it's complete, that would be great. If it's not the case, or it's incomplete, or it leaves out exceptions that could be thrown my methods called from the method, that would really be a drag.

It's pretty complete (exception documentation, that is) in my experience. Every once in a while you'll get an exception that's thrown from deep in the stack that doesn't seem intuitve, but for me it's usually when I'm dealing with remoting or xml stuff. I would think that requiring any framework the size of .NET to document all possible Exceptions that could be thrown from calls to subfunctions is next to impossible (and I think MSDN's documentation had even stated in the past at least that the <exception> doc tag should document excpetions thrown directly from the function itself and not those from sub functions.

--
Doug Semler, MCPD
a.a. #705, BAAWA. EAC Guardian of the Horn of the IPU (pbuhh).
The answer is 42; DNRC o-
Gur Hfrarg unf orpbzr fb shyy bs penc gurfr qnlf, abbar rira
erpbtavmrf fvzcyr guvatf yvxr ebg13 nalzber. Fnq, vfa'g vg?

.

Relevant Pages

  • RE: Handling "exception errors"
    ... The exceptions that get thrown will depend on what code is being run in 'some ... Your best approach would be to check the documentation for the ... very unlikely to have any way to easily correct the underlying issue. ...
    (microsoft.public.dotnet.framework.compactframework)
  • Re: Knowing the exceptions thrown by a method
    ... I would know how could I know what exceptions are thrown by a method ... > code writing time. ... there are no checked exceptions in C#. ... documentation to see what throws what, you 'll just have to trust the ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: How to extract all exceptions for any method
    ... you the specific Exceptions that can be generated by a single method. ... exceptions may be thrown, and inasmuch as VS shows you that documentation,   ... might be thrown wouldn't be relevant information anyway, ... from generic exceptions), so it is possible. ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: How to extract all exceptions for any method
    ... It's true that the documentation for much of .NET includes information as to which exceptions may be thrown, and inasmuch as VS shows you that documentation, it will show you those specific exceptions. ... Other kinds of exceptions that might be thrown wouldn't be relevant information anyway, ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: CLOS and C++
    ... > relative percentage of needing to know the exceptions a given method can raise ... >> with the information provided by the mandatory type declarations. ... javadoc comments and put it into the class file and then change the ... attach the documentation directly to the elements its documenting so ...
    (comp.lang.lisp)