CODEWITHSUNDEEP
c#documentation-generationcode-documentation
GETah
GETah

Reputation: 21419

Documenting exceptions

I have the following public interface

public interface Bar{
   public void DoStuff();
}

with an internal back end class

internal class BarImpl : Bar{
   public void DoStuff(){
     // throw exception if invalid state
     // do something
   }
}

The question:

Does it make sense to document these exceptions in the Bar.DoStuff xml doc?

Thanks in advance,

Upvotes: 1

Views: 214

Answers (3)

jgauffin
jgauffin

Reputation: 101150

I only document exceptions which could be handled. Doesn't make sense to document any other exceptions. My definition of "handling" exceptions is that the method can deliver the promised result by catching the exception.

So this answer is only for those exceptions:

If you want to follow open/closed principle you should document the exceptions for the interface and not the concrete class. And all implementations must throw the same exception when the same scenario occurs.

Upvotes: 1

Justin
Justin

Reputation: 86729

Yes - this would be the case even if BarImpl isn't the only implementor.

The example I like to use is the Stream class where the abstract Read method lists a whole load of exceptions that users of a Stream instance might expect to be thrown when using this method, and in turn the implementors of this class should throw under various scenarios.

Upvotes: 3

Huske
Huske

Reputation: 9296

Yes it does. It helps other developers to be prepared and to handle any exception that might occur. Think how many times it helped you prepare yourself for exceptions by going through MSDN documentation.

Upvotes: 1

Related Questions