Skip to content
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-documenter] 'abstract' missing in "Methods" overview table's "Modifiers" column #3661

Closed
fwienber opened this issue Sep 29, 2022 · 3 comments · Fixed by #3662
Closed

Comments

@fwienber
Copy link
Contributor

fwienber commented Sep 29, 2022

Summary

The "Methods" overview table of a class has a "Modifiers" column, but the abstract modifier does not appear in that column (other modifiers like public do).
A similar issue occurs with the "Classes" overview table of a package or namespace. This does not even have a "Modifiers" column (probably because the assumption is that all documented classes are public?), so you cannot see whether a class is abstract in the overview at all.
On the detail page of both method and class, the "Signature" section does show the abstract modifier.

Repro steps

As an example, use the most simple abstract class with an abstract method:

/**
 * The Foo class.
 * @public
 */
export public abstract class Foo {
  /** The bar method. */
  abstract bar(): void;
}

Expected result:

On the package or namespace overview page, you can see that Foo is an abstract class.
On Foo's details page, in the "Methods" overview table, you can see that bar() is an abstract method.

Actual result:

The abstract modifier of both the class and the method is only mentioned on their details page, in the "Signature" section.

Details

The basic infrastructure to extract and generate Markdown for modifiers is there, but it is only used for other modifiers like public and readonly. It can easily be complemented for abstract.

I already have a local change working that adds abstract to the "Modifiers" column of the "Methods" overview table. For the "Classes" overview, I'd need advice whether to add a "Modifiers" column there, too, or (my preferred solution) to add a dedicated "Abstract Classes" overview table, because in an API, abstract classes are quite something different from a concrete class, sometimes closer to an interface.

I am aware that there are other output targets than Markdown, but did not yet have a look at these in the api-documenter code. They are probably affected and should be updated, too.

To access the abstract modifier of classes and methods, a minor change in api-extractor / api-extractor-model is needed, too.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question Answer
@microsoft/api-documenter version? 7.19.14
Operating system? any
Documentation target? Markdown
Would you consider contributing a PR? Yes
TypeScript compiler version? 4.8.2
Node.js version (node -v)? 16.15.1
@fwienber
Copy link
Contributor Author

To show the state of implementation for anyone interested, I created a draft PR at #3662. Feel free to comment there for implementation aspects. The feature itself should be discussed here in the issue, I guess.

@fwienber
Copy link
Contributor Author

fwienber commented Oct 4, 2022

ping

@zelliott
Copy link
Contributor

zelliott commented Oct 6, 2022

Thanks for opening an issue @fwienber! I think it makes sense for API Extractor to extract whether or not an API item has an abstract modifier - that seems like useful API information for consumers. I'll take a look at your draft PR!

A similar issue occurs with the "Classes" overview table of a package or namespace. This does not even have a "Modifiers" column (probably because the assumption is that all documented classes are public?), so you cannot see whether a class is abstract in the overview at all.

Yeah - my guess for why classes don't have a "Modifiers" column is probably because we (until now) haven't been extracting any modifiers for classes. All classes are "public" in the sense that visibility modifiers like public can't be used on classes. But the abstract modifier can be used, so if we're extracting it for classes, then perhaps it makes sense to add a "Modifier" column for classes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants