Add @deprecated decorator

[madcampos]

Motivation

When changes happen in a project, we may want to mark it as deprecated to alert other developers to avoid using something, and optionally point them to use something else instead.

Proposal

Add a new @deprecated decorator.
The value for this decorator is the message to display about this variable.

E.g.:

# Some old variable
# @deprecated
SOME_OLD_VARIABLE=

# Some old variable, with message
# @deprecated="Use NEW_VARIABLE instead"
ANOTHER_OLD_VARIABLE=

NEW_VARIABLE=

That in turn would add the @deprecated JSDoc annotation to generated types, like so:

export type CoercedEnvSchema = {
  /**
   * **SOME_OLD_VARIABLE** 
   * Some old variable  
   * @deprecated
   */
  SOME_OLD_VARIABLE: string;

  /**
   * **ANOTHER_OLD_VARIABLE** 
   * Some old variable, with message  
   * @deprecated Use NEW_VARIABLE instead
   */
  ANOTHER_OLD_VARIABLE: string;
  
  //...
}

[theoephraim]

Makes sense to me!

[philmillman]

@madcampos are you thinking type only message or would you expect a warning in the varlock load or run?

[madcampos]

I don't know. On one side a warning when the variables are loaded is useful to tell people there are deprecated things.

But also, just type annotation already tells users the thing is deprecated.

Example in VSCode: