odoc icon indicating copy to clipboard operation
odoc copied to clipboard

Support doc comments on function parameters

Open azzsal opened this issue 6 months ago • 1 comments

This should resolve #927. The doc comments for function parameters are collected and stored with the docs for any value description.

azzsal avatar Jun 11 '25 16:06 azzsal

This looks a very good start! So, currently I believe you are "adding" the docstrings attached to arguments, to the docstring attached to the function:

(** G *)
val f :
  int -> (** A *)
  int -> (** B *)
  int

will be turned into:

(** G

A

B
 *)
val f :
  int ->
  int ->
  int

This is close to what we want! We want to embed them inside @param tags:

(** G

@param <param name> A

@param <param name> B
 *)
val f :
  int ->
  int ->
  int

However, as you can see, we need parameter names. One first step would be to enable this only for labelled arguments:

(** G *)
val f :
  x:int -> (** A *)
  y:int -> (** B *)
  int

should be turned into:

(** G

@param x A

@param y B
 *)
val f :
  int ->
  int ->
  int

Let me know if something's unclear or if you need more guidance on how to do that!

The other potential improvements are:

  • Adding a test. It's nice to add it early, even first testing that something does not work, and seeing how each commit influences the test output.
  • You'll need to implement the loading for cmi and cmt as well (actually, maybe those loader reuse the function you've modified, I would need to check!)

panglesd avatar Jun 12 '25 07:06 panglesd