rescript-lang / rescript-lang/rescript-vscode
include ModuleAlias target id in doc extraction
Nobody has claimed this yet.
- Dominant language
- ReScript
- Stars
- 354
- Forks
- 63
- Avg merge
- 11h 29m
- Merged PRs (30d)
- 1
Description
Currently ModuleAlias is defined in DocExtraction.docItem as:
| ModuleAlias of {
id: string;
docstring: string list;
name: string;
items: docItem list;
}
While this differentiates between a module implementation and an alias, there is no way of knowing if 2 aliases reference the same target.
E.g:
// Root.res
module A = Core.Array // {id: "Root.A", name: "A",...}
module B = Core.Array // {id: "Root.B", name: "B",...}
While the above is obviously bad interface design, it becomes more important if we were to extract docs from several different modules, which alias the same module.
When generating documentation for a complete project we most likely want to be able to avoid duplication.
If we were to run doc extraction on every module (file) in the example below, it would be nice to have an id stating the aliased module is the same as the one from another extracted json.
src/
Pkg__A.res
Pkg__B.res
Pkg.res // aliases Pkg__A & Pkg__B
Therefore we need a way to uniquely identify a target module.
P.S: I guess we could compare identities by content of the json structures, but a simple id string is easier to handle.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in analysis/src/DocExtraction.ml at DocExtraction.docItem, especially the ModuleAlias definition shown in the issue. Trace how aliases are extracted and represented, then define and expose a stable identifier for each aliased target so aliases from separate module extractions can be recognized as referring to the same module.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100