title: Best practices: Use of @throws in php-doc, and how it could be handle
body: <p>Let's say I have a class with a method like this:</p>
  
  <pre><code>/*
   *
   * Loads the user from username.
   *
   * @param string $username The username
   *
   * @return UserInterface
   *
   * @throws userNotFoundException if the user is not found
   */
  public function getUser($username)
  {
      // someFunction return an UserInterface class if found, or null if not.
      $user = someFunction('SELECT ....', $username);
      if ($user === null) {
          throw new userNotFoundException();
      }
  
      return $user
  }
  </code></pre>
  
  <p>Now let's say that <code>someFunction</code> could throw a <code>InvalidArgumentException</code> / <code>RuntimeException</code> / <code>PDOException</code> for XYZ reasons. What should I do? <strong>And what not?</strong></p>
  
  <h2>Number 1</h2>
  
  <p>Add all the possible exceptions that could throw <code>someFunction</code> in php-docs.</p>
  
  <pre><code>/*
   *
   * Loads the user from username.
   *
   * @param string $username The username
   *
   * @return UserInterface
   *
   * @throws userNotFoundException if the user is not found
   * @throws InvalidArgumentException
   * @throws ...
   */
  </code></pre>
  
  <h2>Number 2</h2>
  
  <p>Add a try-catch block to ensure that the method should throw exceptions ONLY documented</p>
  
  <pre><code>/*
   *
   * Loads the user from username.
   *
   * @param string $username The username
   *
   * @return UserInterface
   *
   * @throws userNotFoundException if the user is not found
   * @throws RuntimeException 
   */
  public function getUser($username)
  {
      try {
          $user = someFunction('SELECT ....', $username);
      } catch (Exception $e) {
          throw new RuntimeException();
      }
  
      if ($user === null) {
          throw new userNotFoundException();
      }
  
      return $user
  }
  </code></pre>
  
  <h2>Number 3</h2>
  
  <p>Don't do anything.</p>