While it is nice that ocamldoc can auto-generate documentation from .mli
files, it would be very useful if one could just put more information into
.mli files which is irrelevant to the compiler, but displayed faithfully
in the documentation. Two major points come to my mind: (1) names of type
jokers, and (2) embedded comment annotations.
When documenting a function like:
let pointwise comp f g x = comp (f x) (g x)
I would *love* to be able to just put something along the following lines
into the .mli file so that it ends up in the documentation:
===>
val pointwise : ('val_f -> 'val_g -> 'val_f_op_g) (* op *)
-> ('x -> 'val_f) (* f *) -> ('x -> 'val_g) (* g *)
-> ('x -> 'val_f_op_g) (* f_op_g *)
(** One re-occurring construction is the point-wise combination
of two functions: given two functions [f], [g], which have
the same domain, and a binary operation [op] defined on the co-domains
of those functions, we can obtain a new function by mapping a value
[x] to the result of applying the given operation to [f(x)]
and [g(x)], which we will call [f_op_g].
*)
<===
as far as I can tell, this is not possible right now. Or is it?
--
regards, tf@cip.physik.uni-muenchen.de (o_
Thomas Fischbacher - http://www.cip.physik.uni-muenchen.de/~tf //\
(lambda (n) ((lambda (p q r) (p p q r)) (lambda (g x y) V_/_
(if (= x 0) y (g g (- x 1) (* x y)))) n 1)) (Debian GNU)