Documentation strings for structures

[ratsclub]

Problem

Currently, it's possible to document structures with documentation strings:

structure Example: EXAMPLE = struct
  (*! some markdown text *)
  val foo = ()
end

However, it would be nice to default the documentation string from the signature if the structure does not provide one.

Solution

Show the signature documentation string if the structure does not define one.

signature EXAMPLE = sig
  (*! signature foo docs *)
  val foo: unit
  (*! signature bar docs *)
  val bar: unit
end

structure Example: EXAMPLE = struct
  (*! different docstring *)
  val foo = ()
  (*! signature bar docs *)
  val bar = ()
end

In this case, Example.bar would inherit the documentation string from the signature.

[azdavis]

tracked in 0349a3b2a0ba1f1ec59d118d9ede56bc6781b936

[azdavis]

hm actually i think there's actually two main things here. consider this:

signature EXAMPLE = sig
  (*!
   * signature foo docs
   *)
  val foo: unit
  (** ^^^ hover: signature foo docs (1: OK) *)

  (*!
   * signature bar docs
   *)
  val bar: unit
  (** ^^^ hover: signature bar docs (2: OK) *)
end

structure Example: EXAMPLE = struct
  (*!
   * structure foo docs
   *)
  val foo = ()
  (** ^^^ hover: structure foo docs (3: OK) *)

  val bar = ()
  (** ^^^ hover: signature bar docs (4: ERR: actually got no hover) *)
end

val foo = Example.foo
(**       ^^^^^^^^^^^ hover: structure foo docs (5: ERR: actually got signature foo docs) *)

val bar = Example.bar
(**       ^^^^^^^^^^^ hover: signature bar docs (6: OK) *)

this is an expanded example, with a bunch of numbered hover areas, and whether the current output matches what i think you want (OK) or not (ERR with some other undesired hover).

i think you're asking abour (4) in the body of the issue, but IMO i actually care more about (5).

also, i see the argument for why both might be nice, but (5) might be easier to get implemented? also maybe that's why i care more about it? 😂 not sure though.

[azdavis]

implemented as of 0c49cee9f31e679b0e80466351c60f59f9d975a5