I'm working on a package with a significant number of files. Each file exports a runtime function, such as split, and also exports a type-level equivalent, such as Split. All the exported symbols are fully documented, and each module includes a thorough module documentation with examples.
Expected Behavior
I expect both the function and its corresponding type alias to have their respective documentation generated.
Actual Behavior
When I generate the documentation using deno doc, I’m experiencing an issue where not all symbols are properly documented. Specifically, on macOS (which uses a case-insensitive file system), there is a conflict in the generated file names. I assume that deno doc tries to generate both Split.html and split.html. However, only one of these files survives the process due to the case-insensitivity of the file system. The result is that the documentation for one of the symbols is randomly overwritten by the other.
For example, some files end up only documenting the type, while others only document the runtime function. The symbol that ends up being documented is unpredictable and seems to depend on whichever file is generated last, overwriting the previous one.
Here's a quick screenshot that illustrates an indicator of a symbol that's been overwritten:
Additional Observation
Even though the actual files for some symbols are missing, all the symbols still appear in the list of all symbols, as shown in the screenshot below. This inconsistency can be quite confusing when navigating the documentation.
Suggested Solution
While I'm not deeply familiar with the HTML rendering engine's internals, I believe it should be relatively straightforward to implement a mechanism to avoid such conflicts. For example, appending an incrementing numeric value to the end of symbol names that differ only in case could resolve this issue immediately.
crowlKats
commented
3 months ago
Deno Version
Background
I'm working on a package with a significant number of files. Each file exports a runtime function, such as
split, and also exports a type-level equivalent, such asSplit. All the exported symbols are fully documented, and each module includes a thorough module documentation with examples.Expected Behavior
I expect both the function and its corresponding type alias to have their respective documentation generated.
Actual Behavior
When I generate the documentation using deno doc, I’m experiencing an issue where not all symbols are properly documented. Specifically, on macOS (which uses a case-insensitive file system), there is a conflict in the generated file names. I assume that deno doc tries to generate both Split.html and split.html. However, only one of these files survives the process due to the case-insensitivity of the file system. The result is that the documentation for one of the symbols is randomly overwritten by the other.
For example, some files end up only documenting the type, while others only document the runtime function. The symbol that ends up being documented is unpredictable and seems to depend on whichever file is generated last, overwriting the previous one.
Here's a quick screenshot that illustrates an indicator of a symbol that's been overwritten:
Additional Observation
Even though the actual files for some symbols are missing, all the symbols still appear in the list of all symbols, as shown in the screenshot below. This inconsistency can be quite confusing when navigating the documentation.
Suggested Solution
While I'm not deeply familiar with the HTML rendering engine's internals, I believe it should be relatively straightforward to implement a mechanism to avoid such conflicts. For example, appending an incrementing numeric value to the end of symbol names that differ only in case could resolve this issue immediately.