Re: Problems Handling Errors Correctly

Jonathan Wood wrote:
Seriously, I have spent a lot of time looking at .NET documentation. In many respects, I find it severely lacking where many methods or properties have a tiny description that provides no more information than simply looking at the name of the member.

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.

However, that template does include a complete enumeration of interfaces, which is really all I was talking about here. I haven't run across a class for which the docs didn't tell me what interfaces it implements.

For what it's worth, I find MSDN to be FAR superior to other documentation I've had to use, including recently. If you think MSDN is sparse, go check out Apple's developer reference for their APIs, or worse try browsing through man pages trying to figure out Unix stuff. MSDN does a really great job of providing convenient search and cross-references, which goes a long way toward being able to easily connect the dots when a specific doc page is a bit sparse.

[...]
As I mentioned, I had the opportunity to have conversations with several of the .NET developers when it first came out. I have some idea where they are coming from. Personally, I think some of the issues with the .NET documentation is simply due to the depth of the product and the priority, or lack thereof, of being more thorough.

No doubt it is a balance between getting everything documented and having the resources, whether due to cost-cutting measures or simply due to the difficulty in finding qualified staff, to thoroughly document everything.

BTW, one thing I do recall saying to the developers was that the docs should clearly indicate to me whether or not a particular method (or property) can possibly raise an exception. At the time, they agreed but I'm also having trouble seeing any indication of that. Do you happen to know the "magic incantation" to obtain that information?

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.

Pete
.

Relevant Pages

  • Re: if !defined and #pragma once
    ... gaps like these with the 'community content' features of the new MSDN. ... discussion of _MSC_VER, is merely incompetent documentation. ... Blogs are not documentation. ... VS5 was such crap that not only didn't it work very well, ...
    (microsoft.public.vc.mfc)
  • Re: Manifests and requestedExecutionLevel
    ... I agree MSDN is getting pretty sucky, and as MVP's it is our duty to tell ... Yes, perhaps, but since the info going into a manifest comes from diverse ... The keywords unfortunately don't associate with MIC levels. ... but scarcely a documentation issue as the keywords are ...
    (microsoft.public.vc.mfc)
  • Re: Lisp Garbage Collection
    ... find my way through the MSDN? ... codes with no explanations of what they mean. ... In "Linux" system the GNU Info pages, and their HTML mirrors, are the ... best documentation of the Gnu parts of the system, ...
    (comp.lang.lisp)
  • Re: hInstance field in PROPSHEETPAGE structure: MSDN doc not corre
    ... That is unfortunate (the MSDN feedback link being broken). ... I've usually just gone the route of finding the companion doc page in my local SDK documentation and using that for bug submissions instead of trying to go through the MSDN online documentation. ... Windows SDK MVP ...
    (microsoft.public.development.device.drivers)
  • Re: How to get the documents in detail?
    ... Not MSDN Library. ... anyone trying to learn how/when to use a particular interface (I guess ... A halfway decent documentation on this interface would have put the ... blah blah blah is an example of a possible site and a yeah yeah yeah ...
    (microsoft.public.vc.atl)
Loading