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)