RFC: Handling of ambiguous comment blocks

Consider the following TypeScript source file:

/** [1]
 * @file Copyright (c) Example Corporation
 */

/** [2]
 * The Widget class
 */
// [3] TODO: This class needs to be refactored
export class Widget {
  /** [4]
   * The width of the Widget class
   */
  // [5] private width: string;

  /* [6] Renders the class */
  public render(): void {
  }

  /**
   * [7] The height of the widget
   */
  public get height(): number {
  }

  // [8] This is a setter for the above getter
  /**
   * [9] Sets the height
   */
  public set height(value: number) {
  }
}

Which comments are associated with which API items?

We might expect a documentation tool to associate the comments as follows:

• Widget: Uses [2] as its doc comment
• Widget.render: No doc comment, but warn that [6] looks like it was intended to be JSDoc, and warn that [4] doesn’t seem to be attached to anything
• Widget.height: Normally setters/getters are documented as one API item, so use [7] and report a warning for [9]

Does this make sense? Is there an unambiguous algorithm for selecting the right comment?

[octogonz]

We don’t use files-as-namespacs in any of the projects I work on, although I’ve had external requests for this feature that seem reasonable.

API Extractor does rely on file-level comments from the entry point of a package to document the package itself. However, I would be super paranoid about blindly publishing the “first” comment we encounter. What if it’s a copyright banner or other junk that wasn’t intended for customers to see? Or what if we counted wrong, because of the weird way that trivia gets parsed by the compiler (and often omitted from the .d.ts file)? For these reasons we insist on the file comment containing a TSDoc tag @packageDocumentation and do some checks to make sure it’s not missing, nor are there more than one of them.

It’s not great code, but you can see the implementation here: https://github.com/Microsoft/web-build-tools/blob/25d2894edaebb8fc30fe21f13cc691a5e8d78878/apps/api-extractor/src/aedoc/PackageDocComment.ts

I was thinking about revisiting this topic when we add support for namespaces introduced using import * as n1 from ___.

[MartynasZilinskas]

I think there are two possible solutions.

1. Strict. JSDoc comment block must be in immediate previous line.

class Foo {
    /**
     * Some documentation for `bar`.
     */
    public bar: string;

    /**
     * This JSDoc comment block is not part of `bar2`.
     * WARN developer for floating JSDoc comment block.
     */

    public bar2: string;

    /**
     * Same goes here like in `bar2` example.
     * This JSDoc comment block is not part of `bar3`.
     * WARN developer for floating JSDoc comment block.
     */
    // tslint:disable-next-line
    public bar3: string;    
}

1. Sticky. Empty lines separate comment blocks.

class Foo {
    /**
     * Some documentation for `bar`.
     */
    public bar: string;

    /**
     * This JSDoc comment block is not part of `bar2`.
     * WARN developer for a floating JSDoc comment block.
     */

    public bar2: string;

    /**
     * JSDoc for `bar3`.
     */
    // tslint:disable-next-line
    public bar3: string;

    /**
     * JSDoc comment will be assigned for `bar5`. But it was intended for commented property `bar4`.
     */
    //public bar4: string;
    public bar5: string;

    /**
     * WARN developer for a floating JSDoc comment block.
     */
    /**
     * Some documentation for `bar6`.
     */
    public bar6: string;
}