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