dsheets / codoc

OCaml documentation generator
34 stars 5 forks source link

custom annotation for stability #70

Open c-cube opened 9 years ago

c-cube commented 9 years ago

Rust has a documentation pragma for stability (stable/unstable/experimental) that is heavily used in their development process. I think it would be great to have something similar for OCaml libraries, rather than ad-hoc conventions (e.g., batteries' "incubator"). More specifically, I would like some attribute like this:

(** Foobarzes every quux
     @since 3.14
     @unstable *)
val foobar : quux -> unit

(** A more conventional foo converter to bar
     @stable *)
val make_bar : foo -> bar
Drup commented 9 years ago

It would be nice to be able to put the annotation on a whole module, too. You can see how it renders in rustdoc here: http://doc.rust-lang.org/1.0.0-alpha.2/std/index.html#modules