[api-extractor] Relax the requirements for "@packageDocumentation" tag

[octogonz]

Summary

This is a proof-of-concept fix for the issue that @wachunga reported in https://rushstack.zulipchat.com/#narrow/stream/262521-api-extractor/topic/packageDocumentation

Details

Normally API Extractor requires the @packageDocumentation doc comment to be the first comment in the entry point file. This policy avoids confusing problems that can occur due to the compiler not emitting certain comments in the .d.ts file.

But @wachunga had trouble this policy because his .d.ts file is generated by the Rollup tool. This PR enables a workaround, where the "ae-misplaced-package-tag" message is suppressed. The important change is for API Extractor to accept the misplaced comment rather than discarding it.

See the Zulip thread for more details.

How it was tested

1. The Rush Stack build tests passed.
2. Confirmed that @wachunga's repro is fixed
3. Tried some other cases manually

[wachunga]

Here's a sample .d.ts file that is generated for me by rollup-plugin-dts, with the comment in an unpredictable location:

/// <reference types="react" />
import { ComponentType } from 'react';

declare const FOO = "bar";

/**
 * Identifier used to authenticate.
 *
 * @public
 */
declare type ClientId = string;


/**
 * My package
 *
 * @packageDocumentation
 */
/**
 * Offset for positioning the button relative to the bottom right corner.
 *
 * @public
 */
interface ButtonOffset {
  /** Horizontal offset for the button. */
  x?: number;
  /** Vertical offset for the button. */
  y?: number;
}

export { ButtonOffset, ClientId  };

[octogonz]

Here's a sample .d.ts file that is generated for me by rollup-plugin-dts, with the comment in an unpredictable location:

Thanks! I validated that it works correctly with this build.

By default, it prints this warning (but successfully incorporates the comment into the doc model):

api-extractor 7.13.0  - https://api-extractor.com/

Using configuration from ./config/api-extractor.json
Analysis will use the bundled TypeScript version 4.1.3
Warning: The API report file was missing, so a new file was created. Please add this file to Git:
C:\test-project\etc\example.api.md
Warning: lib/example.d.ts:13:1 - (ae-misplaced-package-tag) The @packageDocumentation comment must appear at the top of entry point *.d.ts file

And then if I add this to api-extractor.json, then the ae-misplaced-package-tag warning is not displayed:

    "extractorMessageReporting": {
      "default": {
        "logLevel": "warning"
        // "addToApiReportFile": false
      },
      "ae-misplaced-package-tag": {
        "logLevel": "none"
      }
    },

👍 Looks good