odoc
odoc copied to clipboard
Support doc comments on function parameters
This should resolve #927. The doc comments for function parameters are collected and stored with the docs for any value description.
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!)