RFC: @defaultValue to indicate a default value

[octogonz]

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?

[typhonrt]

This tag seems to still be useful for properties and fields. It seems less applicable for function parameters with the introduction of default values accessible in the AST with ES6+ and TS. However, it's still applicable on the JS side of things IMHO due to call time evaluation and default parameters being available for later evaluation (examples taken from here):

function callSomething(thing = something()) {
 return thing;
}

function something() {
  return 'sth';
}

or default parameters being available to later default parameters

function singularAutoPlural(singular, plural = singular + 's', rallyingCry = plural + ' ATTACK!!!') {
  return [singular, plural, rallyingCry]; 
}

Granted JS examples on tricky edge cases, but likely as well w/ TS? The @param w/ types and default values JSDoc syntax handles this for function parameters. It would be interesting to see the TS counterpart to the above perceived edge cases.

The examples above would cause trouble for various documentation tooling pipelines likely as resolving things requires a two pass algorithm and potential evaluation which can be fragile where the @default @param w/ default values syntax provides up front clarification.

[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]

I noticed that although JSDoc supports @default as shown above, it also allows @default to act as a modifier tag that instructs a documentation engine to show the assigned value of a variable. This is the example they give:

Document the number value of a constant

/**
 *  @constant
 *  @default
 */
const RED = 0xff0000;

I interpret this to mean that, JSDoc parses @default as a block tag if there's more text on the same line, otherwise it's parsed as a modifier tag. Since TSDoc doesn't force each tag to be on its own line, this is unconventional and likely to cause confusion.

I'm also not even sure this is needed with TypeScript. In my experience the type system already makes it fairly easy to determine whether or not a variable is a constant whose value should be documented.

Since JSDoc defines @defaultvalue as a synonym, I propose the following refinements:

• TSDoc should use @defaultValue (block tag) for the original scenario we discussed ONLY. The name @defaultValue makes it more obvious that you must provide some text.

• TSDoc should reserve @default (modifier tag) as a "discretionary" tag. Its exact meaning will be left to implementors, but by saying that it's a modifier tag, we're clear that the text after it cannot be treated as an argument.

This ensures that the two scenarios don't get confused, and we won't need a special grammar rule to handle this tag.

[octogonz]

Updated 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.
   * 
   * @defaultValue `WarningStyle.DialogBox`
   */
  warningStyle: WarningStyle;

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

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

[octogonz]

@kkjeer

[aciccarello]

Related TypeStrong/typedoc#856

Typedoc show values but in some cases that isn't desired, such as here when the text is super long.

[sindresorhus]

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

[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: #151