How to document @throws in interface documentation

documentation, exception, interface, oop, php

Solution

Consider code where you consume the interface:

public function doSomething(MyInterface $my) { ... }

If even one of the implementations can throw an exception, you'll want to make sure you handle the possibility of exceptions.

So, yes, it should be documented.

Even if only one implementation throws an exception, exception handling still needs to be in place. Of course this doesn't mean that every method should have a @throws slapped on it. It should still only be used where appropriate (where you're expecting an implementation to legitimately need to throw an exception).

As a more concrete example, consider the following:

interface LogWriter
{

    /**
     * @throws LogWriterException
     */
    public function write($entry);

}


class DbLogWriter
{

    public function __construct(PDO $db)
    {
        //store $db somewhere
    }

    public function write($entry)
    {
        try {
            //store $entry in the database
        } catch (PDOException $e) {
            throw new LogWriterException(...);
        }
    }

}

class NullLogWriter
{
    public function write($entry) { }
}

Certain things could be done to attempt to lower the probability of an exception when writing to the database, but at the end of the day, it's not an exception safe operation. Therefore, `DbLogWriter::write` should be expected to throw exceptions.

Now consider the null writer though, that just discards entries. There's absolutely nothing at all that could ever go wrong there, therefore, no need for exceptions.

Yet what if you have some `$log` and all you know about it is that it's an implementation of `LogWriter`. Do you assume it doesn't throw exceptions and potentially accidentally let one bubble up, or do you assume that it can throw a `LogWriterException`? I would stay on the safe side and assume that it can throw a LogWriterException.

If all the user knows is that the `$log` is a LogWriter but only DbLogWriter is documented as throwing an exception, the user may not realize that `$log->write(...)` can throw an exception. Also, when FileLogWriter is later created, it would mean the expectations of what exceptions that implementation can and possibly will throw will already be set (no one would expect the `FileLogWriter` to throw a `RandomNewException`).

Problem

I'm writing a PHP library and I have a concern. I have something similar to the following in my interfaces: ``` <?php /** * My interface * * ... */ interface MyInterface { /** * This method does foo. * * @throws \RuntimeException If foo can't be done. */ public function fooAndBar(); } ?> ``` Now, the `@throws`entry isn't perfectly right, since an interface doesn't actually do anything, and is used purely to abstract implementation details. However, I've always used it because all my implementations of the interface thrown the exception when something goes wrong. But another developer might write an implementation that can't fail (so it can't throw an exception), or he/she might want to use another exception class. In this situation, how should I document `@throws` in interface declarations? Should it even be documented?

Original source