System.Data.SQLite

Login
This project makes use of Eagle, provided by Mistachkin Systems.
Eagle: Secure Software Automation
Ticket Hash: 1c2dd41f57e0a1019eaf450623b36d8ea565fa5c
Title: Is it possible to document exceptions that are thrown via the xml comment?
Status: Closed Type: Documentation
Severity: Minor Priority: Low
Subsystem: Doc_Automation Resolution: Works_As_Designed
Last Modified: 2014-01-23 01:59:31
Version Found In: All versions (but I'm using 1.0.64)
Description:
There is no documentation of what/when exceptions are thrown from any objects under the System.Data.SQLite.dll library. Is it possible to add these to the xml comments (using /// <exception cref="exception type">Reason why thrown</exception>) so that both the SQlite.Net.chm help and Visual Studio Intellisense will display them?

At the moment, the only way for me to know when to use a try/catch (and what to catch other than a generic Exception object), is to look at the inherited base classes or implemented interfaces on MSDN or to look at the source code and look for thrown exceptions.

If this is not much of a priority, I would even be willing to add the xml comments to the source code myself and pass them back to the project to be merged in by an administrator.

Thanks

Jason Down


mistachkin added on 2011-09-17 16:53:42 UTC:
Documenting the exceptions thrown by any method can be a tricky business:

1. Do you only document exceptions explicitly thrown or ones that could occur as a result of attempting something that can throw?

2. Do you document exceptions thrown by child components that can "escape" outward?

3. Do you document exceptions that can be thrown by the framework methods used by the method?

etc.


anonymous claiming to be Aldur added on 2012-11-14 23:30:26 UTC:
You should document any exception (regardless of it's source), that may effect developer code decisions. This includes: decision if to use try/catch and decision to react in custom way to any particular exception.


mistachkin added on 2012-11-16 19:19:14 UTC:

In practice, it's very hard to determine the exact exceptions that can be thrown by any given built-in .NET Framework method as they are not always exhaustively documented.