Provide a way to hide code blocks in `.mld` files

[dbuenzli]

With new features comes new wishes :–)

When you do code extraction you sometimes have setup code (e.g. a license header) that you'd like to hide in the rendering. With mli files you can simply use a stop comment but in .mld files there is no such thing, everything gets rendered, as noticed in #998.

I think we should standardize an info string tag, e.g. @hidden which should work regardless of whether we are processing .mld file or a cmti one and that removes the tagged code block from the rendering.

So for example I can have:

{@ocaml @hidden name=header[
(*---------------------------------------------------------------------------
   Copyright (c) 2011 The cmdliner programmers. All rights reserved.
   SPDX-License-Identifier: CC0-1.0
  ---------------------------------------------------------------------------*)
]}

And then:

{@ocaml name=example1.ml[
…
|}

{@ocaml name=example2.ml[
…
|}

And extract the examples as

 odoc extract-code --name header --name example1.ml
 odoc extract-code --name header --name example2.ml

[jonludlam]

Yes, this is a good idea. I'm not sure whether we should go with @hidden or just hidden - I can see why using the same string as the tag is nice, It'll look a bit odd if other atoms/bindings don't also start with an '@', and that seems unnecessary.

[dbuenzli]

I'm not sure whether we should go with @hidden or just hidden

Neither I am :–) Initially I was more leaning towards @-less. But arguments in favour are that it gives a strong hint that this will be interpreted by odoc rendering and that such a tag could be introduced in the ocamldoc language in the future.

[dlesbre]

Another use case: when using MDX, It would be nice to hide some code blocks which are used to setup examples like #require 'mylib';; or #install_printer MyLib.pp;;.

MDX supports prelude for some definitions but, as far as I'm aware, you can't #install_printer in such a prelude.