rescript-lang / rescript-lang/rescript-vscode

include ModuleAlias target id in doc extraction

Open
#886 9 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.