handling of module types (in doc extraction)

[woeps]

Currently, it seems to me there is no distinction made between a module and a module type in doc extraction (I believe, this is true for the LSP as well?). The extracted docs (json) gives no hint, that it's a module type and not an actual implementation.

Furthermore, any implementing module explicitly annotated with the module type is being ignored in doc extraction:

The following rescript code:

// ModuleType.res

/***
extracted docs don't give a hint, that Example is not an implementation, but a module type

module M is missing in extracted docs
*/

module type Example = {
  /***
  this is an example module type 
  */

  /**
  main type of this module 
  */
  type t

  /**
  function from t to t
  */
  let f: t => t
}

module M: Example = {
  /***
  implementation of Example module type
  */

  /**
  main type 
  */
  type t = int

  /**
  identity function
  */
  let f = (x: int) => x
}

produces this json:

{
  "name": "ModuleType",
  "docstrings": ["extracted docs don't give a hint, that Example is not an implementation, but a module type\n\nmodule M is missing in extracted docs"],
  "items": [
  {
    "id": "ModuleType.Example",
    "name": "Example",
    "kind": "module",
    "docstrings": [],
    "items": [
    {
      "id": "ModuleType.Example.t",
      "kind": "type",
      "name": "t",
      "signature": "type t",
      "docstrings": ["main type of this module"]
    }, 
    {
      "id": "ModuleType.Example.f",
      "kind": "value",
      "name": "f",
      "signature": "let f: (. t) => t",
      "docstrings": ["function from t to t"]
    }]
  }]
}

I'm honestly not sure how I'd expect it to be represented in the extracted json. (kind currently being one of Value, Type, Module)

1. I believe the minimal requirement is to distinguish an actual module implementation from a module type, since I won't be able to actually call the lather one. [addressed in distinguish regular modules from module types #925]
2. Any (Sub-) Module (not hidden by a *.resi file) should be present in the docs.
3. There is no autocompletion help by the LSP to help with annotating the module type with a module type being a submodule in the same file. (The LSP helps annotating the module type, when the module type from another file is used.)
4. The LSP doesn't distinguish between module and module type as well:
   Typing let x = ModuleType.Example., LSP offers completion for ModuleType.Example.f. - Which is just defined in the module type. Therefore this will yield a compilation error. [addressed in distinguish regular modules from module types #925]

[woeps]

Any advice on how/where I should start trying to fix this myself?

I'd be willing to try to find a solution, but I'm not sure where to start.

[zth]

It indeed seems like there's not real distinction made between modules and module types. @cristianoc any insight?

[cristianoc]

I would start with hover on a module using the vscode extension, eg a file or a locally defined sub module.
Then put a module type in it, see if it shows up in hover.
Look at the hover code to see if there's info for module types / distinction wrt modules in the internal representation
Once that's clear, look at doc extraction.

[zth]

@cristianoc 🙏 that did it: #902

[woeps]

@zth afaiu #925 successfully addresses 2 (out of 4) of my points in the description:

1. I believe the minimal requirement is to distinguish an actual module implementation from a module type, since I won't be able to actually call the lather one.

4. The LSP doesn't distinguish between module and module type as well:
   Typing let x = ModuleType.Example., LSP offers completion for ModuleType.Example.f. - Which is just defined in the module type. Therefore this will yield a compilation error.

After merging #925 a module annotated with a module type will still be missing in the generated docs and LSP auto completion still won't take inline modules in the same line (above) into account.