Skip to content

Support doc comments on function parameters #1353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

azzsal
Copy link
Contributor

@azzsal azzsal commented Jun 11, 2025

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

@panglesd
Copy link
Collaborator

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!)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Doc comments on function parameters
2 participants