Include headings in synopsis

[Julow]

Heading were skipped while computing the synopsis for a module. Now the heading's text is used when it's the first element.

In the examples from #235, the CCArray module wouldn't have a synopsis in {!modules:...} lists. This PR doesn't answer the rest of the discussion.

[dbuenzli]

What is this PR supposed to solve ? The issue reported in #235 is not about giving a synopsis to CCArray it's about it's first heading not showing up in the toc and showing up in .odoc-preamble rather than.odoc-contents.

More precisely this PR changes the definition of synopses from take the first paragraph to take the first paragraph or the contents of the first heading. I'm against this, this has never been an established practice and I don't think it makes sense (headings in modules are used to section the module's contents).

[Julow]

This PR is not solving any issue, I'm just proposing to change the definition of synopsis.
I found that ocamldoc does this. I'll close.

[dbuenzli]

I found that ocamldoc does this. I'll close.

Just for the record ocamldoc does not do this. Namely no synopses are to be seen with the following invocations:

> cat a.mli
module B : sig
  (** {1:bla First header } *)
end
> ocamlc a.mli 
> ocamldoc -I . -html a.mli
> open index.html 

Using this definition would mean that 1) a lot of modules would get bogus synopses 2) What is a synopsis for a module and what is a header for a module become messy concepts.

[Julow]

I can reproduce with:

(** {1 Heading}

    Doc for A. *)
module A = struct

end

(** {!modules:Ocamldoc_example.A} *)

The synopsis is what goes into the {!modules:} list.

Edit: the documentation attached to the definition of A is just "Heading" unformatted, the rest of the comment is not shown in the top-level module, Odoc would show all of it.

[dbuenzli]

Ah interesting! So basically it's totally confusing. It's better to settle on what was agreed on #597 for odoc.