RFC: Support for dot syntax on @param

I’m currently working with d.ts files where methods taking object parameters are documented with the following approach:

/**
* Method description.
* @param options addItemOptions - e.g. { id: 1234, title: "someTitle" }
*             id: The unique identifier.
*             title: The title to assign.
**/

It’s challenging to parse and auto-generate documentation for these parameters given this approach. Ideally there’d be support for dot syntax e.g.:

@param options.id - The unique identifier.
@param options.title - The title to assign.

[dschnare]

What’s more of a pain to document is destructured arguments:

/**
 * Call home.
 * @remarks
 * This texts Mom a message.
 * @param message - The message to send to Mom
 * @param ? - The number of seconds to delay calling home
 * @public
 */
function callHome (message: string, { delay = 0 }: { delay?: number } = {}) {
  // TODO: send a text to Mom!
  throw new Error('Unimplemented')
}

[octogonz]

For APIs intended for third parties, generally we recommend to give a name to the interface, for example:

/** Options for {@link ItemCollection.add} */
interface IAddItemOptions {
  /** the identifier */
  id: string;
  /** a title, not to exceed 40 characters */
  title: string;
}

class ItemCollection {
  /**
   *  Adds an item to the collection
   * @param options - information about the item to be added
   */
  public add(options: IAddItemOptions): void {
  }
}

Naming the interface improves the structure of the documentation. It also helps developers when they need to work with the object independently, for example:

const options: IAddItemOptions = this.getOptions();
collection1.add(options);
collection2.add(options);

That said, I believe TypeDoc supports the @param options.id notation. If people find it useful, we could include it in the TSDoc standard.