[api-documenter] Output files get overwritten for declarations with differences in character case

[JCMais]

I was trying to document the following class:
https://github.com/JCMais/node-libcurl/blob/397120ecc54d804eddc34d83b0e1c286abc08fd9/lib/Curl.ts#L83

Which has an augmentation using an Interface below itself:
https://github.com/JCMais/node-libcurl/blob/397120ecc54d804eddc34d83b0e1c286abc08fd9/lib/Curl.ts#L509

This module also exports another symbol called curl:
https://github.com/JCMais/node-libcurl/blob/397120ecc54d804eddc34d83b0e1c286abc08fd9/lib/curlFn.ts#L154

I found two problems:

1. The Curl class would generate a file node-libcurl.curl.md, but the curl variable above also generates a file with the same name, so the one for the Class is overwritten.

2. If I rename the curl function to something else, the node-libcurl.curl.md now mentions the Curl Interface, and not the Curl 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.

[octogonz]

(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:

• Function overloads sometimes are displayed with the same name ([api-documenter] Function overloads sometimes are displayed with the same name #881)

• Error caused by using the same name for an interface and namespace ([api-extractor] Error caused by using the same name for an interface and namespace #1108)

• yaml validation error for static/instance methods with same name ([api-documenter] yaml validation error for static/instance methods with same name #1252)

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 curl and a class Curl, they obviously need to get different URLs, even thought our URLs are all lower-case.

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.

[JCMais]

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.

[octogonz]

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.