-
Notifications
You must be signed in to change notification settings - Fork 595
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] Output files get overwritten for declarations with differences in character case #1281
Comments
(To clarify, in TypeScript "augmentation" has a special meaning documented here and requested for API Extractor in #1045. By contrast, it sounds like your issue is really about ordinary declaration merging, not augmentation.) There are actually several existing issues relating to this:
They all got tripped on on the design question of how to assign a "unique, stable, and nice" name for arbitrary TypeScript declarations, as summarized in #1252 (comment). API Extractor itself already solves this by using declaration references as the key for the @microsoft/api-extractor-model file. Thus this is really an api-documenter problem, and if we can agree on the right design, the implementation in MarkdownDocumenter.ts is simple and should be easy to fix. I'm not going to resolve your issue as a dupe however, since you've identified a new source of ambiguity that we overlooked: Character casing. If a library exports a function We really need to prioritize this fix. I'll see if I can find some time to work on it myself. Otherwise, anyone else can feel free to update one of these issues with a proposed design. |
Thanks for the clarification and for taking the time to summarize the issues @octogonz. Later on this week I will check if I can help with any of those open issues. |
This issue belongs to a family of closely related issues. I've created metaissue #1308 to come up with a unified fix that tackles them all together. |
I was trying to document the following class:
https:/JCMais/node-libcurl/blob/397120ecc54d804eddc34d83b0e1c286abc08fd9/lib/Curl.ts#L83
Which has an augmentation using an Interface below itself:
https:/JCMais/node-libcurl/blob/397120ecc54d804eddc34d83b0e1c286abc08fd9/lib/Curl.ts#L509
This module also exports another symbol called
curl
:https:/JCMais/node-libcurl/blob/397120ecc54d804eddc34d83b0e1c286abc08fd9/lib/curlFn.ts#L154
I found two problems:
The
Curl
class would generate a filenode-libcurl.curl.md
, but thecurl
variable above also generates a file with the same name, so the one for the Class is overwritten.If I rename the
curl
function to something else, thenode-libcurl.curl.md
now mentions theCurl
Interface, and not theCurl
class which I expected it would, since the declarations are merged.Am I having wrong expectations here? The
Curl
interface was needed to generate better type hints for the library users, but looks like it's causing some trouble. Is there any workaround?The
curl
function I suppose I will need to rename to something else, since the files will always have the same name.The text was updated successfully, but these errors were encountered: