codoc icon indicating copy to clipboard operation
codoc copied to clipboard

custom annotation for stability

Open c-cube opened this issue 10 years ago • 1 comments

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

c-cube avatar Mar 04 '15 12:03 c-cube

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

Drup avatar Mar 04 '15 12:03 Drup