Add support for some JSDocs declarations such as @throws and @deprecated

[amoreaulemay]

I think it could be useful to add support for some JSDocs rules that don't have a direct TypeScript equivalent, such as @throws and @deprecated.

@throws

This could be two folds:

1. Force error handling for consumers of functions that may throw. It could even force exhaustive error handling too. It could be a warning by default maybe.
2. Force declaring JSDocs with @throws when there's an explicit throw and/or it rethrows an error.

Example

/**
 * @throws {MyCustomError1} Thrown when a == 1 // <- Here biome forces the `@throws` JSDoc declaration; and must be exhaustive
 * @throws {MyCustomError2} Thrown when a != 1
 */
function myFunction(a) {
  if (a === 1) {
    throw new MyCustomError1()
  }

  throw new MyCustomError2()
}

function myConsumer() {
  try { // <- Here biome forces handling
    myFunction(1)
  } catch (error) { // <- Exhaustive error handling
    if (error instanceof MyCustomError1) {
      // ...handling
    } else if (error instanceof MyCustomError2) {
      // ...handling
    } else {
      // Leaving a default for other error types
    }
  }
}

@deprecated

Self explanory but consumers of functions with a JSDoc @deprecated declaration should trigger a biome warning/error.

Example

/**
 * @deprecated - Don't use this!
 */
function dontUseThis() {
  // ...
}

function myConsumer() {
  dontUseThis() // <- Here biome triggers a warning
}

[arendjr]

I think both would be useful to have, but I'm not sure we currently have the infrastructure to do something like this. I think once we start implementing type inference, we may have the ability to store such annotations as well. Maybe @Conaclos has some insight here :)

[neemski]

Hey @arendjr - just curious any update here? Would be very useful to have biome warn on @deprecated code usage

[arendjr]

You're in luck! I added a rule for @deprecated just yesterday, though it's focused on imports only: #7520

Let me know if that suits you!

[amoreaulemay]

Awesome @arendjr ! That's a big improvement

[neemski]

Great timing! 😄 Thanks so much @arendjr this is huge! 🙏

[RedEagle-dh]

Sounds great! Excited to try it out! 👍🏽

[redbmk]

@todo would be another cool one to support, so we could flag it as a warning and make TODOs easier to find

[RedEagle-dh]

I would love to see the warning if using a method or function decelerated with @deprecated. This would help to see very early which function is marked as deprecated and will be removed in the future!

[AstroGD]

+1 Would love to see this, especially for deprecated code

[wottpal]

Same here! Current only solution is to fall back to eslint :/