Document exceptions thrown by methods called by a public method

160 views Asked by At

Do I, or do I not, document exceptions thrown by methods begin called by a public method? Based on what I've read, I should try to document such exceptions, which makes sense. At the same time, it can quickly turn out to be "impossible" to document all exceptions that can be thrown.

Also, unless I've misunderstood how to check what exceptions are being thrown by a .NET method, it seems as though Microsoft doesn't document all exceptions that can be thrown by a method. XmlReader.Create() lists four exceptions that can be thrown: System.ArgumentNullException, System.Security.SecurityException, System.IO.FileNotFoundException and System.UriFormatException. I tried to pass in a uri starting with "htp://" to see what exception would be thown. I got a System.NotSupportedException, which was ultimately thrown by System.Net.WebRequest.Create(..).

Am I correct in that Microsoft doesn't document all exceptions that can be thrown, or am I misunderstanding something.

In my own method below, I'd document ArgumentOutOfRangeException and NotValidSyndicationException, but should I also document the four exceptions thrown by XmlReader.Create() mentioned above? What about the System.NotSuppoedException, or System.Net.WebException (thrown when there's no endpoint at the specified uri), which is yet another exception not documented but that has to be "found out by trial and error by me".

public IEnumerable<SyndicationItem> GetItems(int count)
{
        if (count <= 0)
        {
            throw new ArgumentOutOfRangeException("count", "Count must be positive.");
        }

        IEnumerable<SyndicationItem> items;
        using (var rssReader = XmlReader.Create(this.uri))
        {
            var feedFormatter = new Rss20FeedFormatter();
            if (feedFormatter.CanRead(rssReader))
            {
                feedFormatter.ReadFrom(rssReader);
                items = feedFormatter.Feed.Items.Take(count);
            }
            else
            {
                throw new NotValidSyndicationException("The uri does not point to a valid syndication.");
            }
        }
        return items;
}
0

There are 0 answers