RFC: @defaultValue to indicate a default value

In API Extractor issue #720 @RueDeRennes asked about supporting @default to indicate a default value.

Some questions:

• Should this be part of core TSDoc?
• Should the tag be @default or @defaultValue?
• Should it apply only to properties and fields? What about function parameters?

[octogonz]

Based on the discussion with office-ui-fabric-react, we’re thinking @default tag would have the following spec:

• The tag must only be used with fields or properties that are members of a class or interface. For example, @default should NOT be applied to a function or class declaration.
• It’s a normal block tag, which means that it captures all text including multiple paragraphs until the next block tag or the end of the comment.
• That content should be thought of as English prose that would appear on a web site under a heading such as ‘Default Value’.
• In most cases the default value will be code symbols, which should be quoted using a code span (single backticks) or code fence (triple backticks).

Usage example:

enum WarningStyle {
  DialogBox,
  StatusMessage,
  LogOnly
}

interface IWarningOptions {
  /**
   * Determines how the warning will be displayed.
   *
   * @remarks
   * See {@link WarningStyle| the WarningStyle enum} for more details.
   * 
   * @default `WarningStyle.DialogBox`
   */
  warningStyle: WarningStyle;

  /**
   * Whether the warning can interrupt a user's current activity.
   * @default 
   * The default is `true` unless
   *  `WarningStyle.StatusMessage` was requested.
   */
  cancellable?: boolean;

  /**
   * The warning message
   */
  message: string;
}

[octogonz]

How about documenting default function parameters? What will that look like?

@sindresorhus After thinking about this question, I don’t think @defaultValue is the right tag for this. I opened a separate GitHub issue to discuss your question: https://github.com/Microsoft/tsdoc/issues/151