phpcommentsdocblocks

Using DocBlocks on PHP, Should I use @throws when I do not handle errors with execpetion?


I have a class for handling errors, and it is not using the try-throw-catch mechanism.

When I am commenting code that uses that class, should I use the the @throws tag even though I do not actually throwing anything?

EDIT (try to make my question more clear):

My question is if the @throws tags means that an error could occure when using the code and I am handling it in some way, or it means that an error could occure and I am handling it by using the throw keyword specifically?


Solution

  • After reading the documentation, I realize that this is not exactly spelled out.

    The documentation on @throws suggests that if the throw keyword is present at all inside the block of code, then it should be documented for each type of exception that could be thrown regardless of whether or not you're handling it or not.

    So if you have

    try {
        throw new Exception();
    } catch (Exception $e) {
        // handled!
    }
    

    put a @throws entry in the docblock.