-
Notifications
You must be signed in to change notification settings - Fork 607
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[api-extractor] Getting around (ae-forgotten-export) for certain cases #1235
Comments
This is a pretty easy enhancement. There was a plan for a config/api-extractor-suppressions.txt file (see PR #1120), but that feature got cut from AE7 so we could release it faster. FYI I also proposed an @suppress tag for TSDoc, but the consensus was that doc comments aren't a good place to represent suppressions. |
@akshay-madhukar I should also point out that by default the {
. . .
"messages": {
"compilerMessageReporting": {
"default": {
"logLevel": "warning"
}
},
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
},
"ae-forgotten-export": {
"logLevel": "warning",
"addToApiReportFile": true // <--- THIS
},
. . .
},
"tsdocMessageReporting": {
"default": {
"logLevel": "warning"
}
}
},
. . .
} The resulting API report will look like this: // Warning: (ae-forgotten-export) The symbol "Y" needs to be exported by
// the entry point index.d.ts
//
// @public (undocumented)
export class X extends Y {
} When this happens, the message is not counted as a console warning, and thus it will NOT break the build. In other words, the api-extractor tool will return process exit code 0 which indicates success. Thus, although it's slightly annoying to see these warnings in the API report file, they shouldn't cause any trouble. If any new warnings are introduced later, that would cause a diff in the report file, so you'll be able to catch them during a PR code review. |
Hey @octogonz, I'm coming across this as well. I have an internal-only type which is used to create a larger exported type, but I don't want to export the internal-only type. Basically something like this: interface PartialComponentProps {
a: string;
b: string;
}
export type ComponentProps = PartialComponentProps & {
c: string;
}; We would like to be able to mark By the way, we have api-extractor configured with "ae-forgotten-export" set to "error" so that we get an automated check that we're exporting everything we intend to during the build, but we need the ability to remove certain types from the forgotten-export check. |
@gregjacobs It sounds like you want to eliminate the /**
* Nobody is supposed to import this interface directly; it is merely an
* auxiliary definition that helps us declare `ComponentProps`, which is
* the thing that people should import.
* @internal
*/
interface PartialComponentProps {
a: string;
b: string;
}
/**
* @public
*/
export type ComponentProps = PartialComponentProps & {
c: string;
}; But then API Extractor is going to report ae-incompatible-release-tags because a In your example, Thus it seems that Maybe the tag name would be something like /**
* @partial
*/
interface PartialComponentProps {
a: string;
b: string;
} (Related, I recall that @rbuckton had proposed a declaration reference syntax for linking to unexported members of a module.) If we can decide on a design, making the PR is pretty easy. |
I'm not 100% sure about the tag name, but Other words along those lines: |
Another idea would be to model this using For example: /** {@partOf ComponentProps} */
interface PartialComponentProps {
a: string;
b: string;
}
/**
* Represents the properties for a component
* @remarks
* More details here.
* @public
*/
export type ComponentProps = PartialComponentProps & {
c: string;
}; Then the generated API docs would treat them as a single entity:
Advantages of this approach:
Disadvantages of this approach:
|
For the example shared earlier:
It's not clear to me why an |
I really like the partof tag idea! |
This issue is three years old now, are there any recommended options for solving it? I have an API report which complains of |
@octogonz and I just spoke a bit about this today and agreed that there's an opportunity to handle this better. My use case is slightly different from yours and is as follows:
In the case above, my team considers One idea we discussed (@octogonz correct me if I've misremembered anything) was to add a new Then, we discussed using some doc comment tag to (1) silence the ae-forgotten-export warning on a per-declaration basis and (2) control on a per-declaration basis whether the declaration should be included in the API report and doc model. Notably, we didn't talk much about the |
Is there any way to suppress warnings from being written into the
.api.md
files, but only for particular instances. I do not want to turn offae-forgotten-export
entirely. Is a tag or command that could be used to disable warnings similar totslint-disable
?For example, in the following react code:
I do not want to export the interface
BackstageState
as the state of the React component would only be available in the component itself. The interface is purely an implementation detail. If I were to export the interface and set it to internal, there would be anae-incompatible-release-tags
warning instead.Would there be a way to turn of the warnings just for this component and not for the entire package?
The text was updated successfully, but these errors were encountered: