Skip to content
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

ocamldoc: loses parameter descriptions without even warning #7693

Open
vicuna opened this issue Dec 20, 2017 · 0 comments

Comments

Projects
None yet
1 participant
@vicuna
Copy link

commented Dec 20, 2017

Original bug ID: 7693
Reporter: @ygrek
Status: acknowledged (set by @damiendoligez on 2018-06-05T14:49:34Z)
Resolution: open
Priority: normal
Severity: major
Version: 4.05.0
Category: ocamldoc
Monitored by: @nojb @gasche @dbuenzli

Bug description

It seems that @param id only works for named arguments, this is not mentioned in the manual afaics. It means when function has unnamed arguments then @param declarations are just ignored, also if named parameter doesn't match @param name the latter is ignored too. I would expect at least a warning when @param is ignored and I would better suggest to never drop user-supplied documentation even if it seems wrong to ocamldoc.

Steps to reproduce

$ cat a.ml

(** @param x argument to increment*)
let unnamed x = x + 1

(** @param x argument to increment *)
let named ~x = x + 1

(** @param x argument to increment *)
let misnamed ~y = y + 1

module type X = sig

(** [f1 x]
@param x argument to increment
@return result
*)
val f1 : int -> int

(** [f2 ~x]
@param x argument to increment
@return result
*)
val f2 : x:int -> int

(** [f3 ~x]
@param x argument to increment
@return result
*)
val f3 : y:int -> int

end

$ ocamldoc a.ml -html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.