Remarks on odoc's doc

[panglesd]

I collect here the remarks I had when reading the doc. Please tell me if I should do things differently, split the issue in several smaller issues...

Page Odoc for authors

1. (Maybe this is not related to odoc's doc itself, but: ) In the example given just before the "Basic markup" section, the css seems a bit broken for Variants/Records with comments: Maybe adding a width of 100% for tables improves this?
2. In the example about scope

val x : int
val y : int

module A : sig
  (** In this module I can refer to val {!x} declared above as well as
      type {!u} declared later in the parent module. Elements declared
      in this signature take priority, so {!y} refers to {!A.y} as
      opposed to the [y] declared in the parent signature.  *)

  val y : string
end

type u

Is there a way to refer to the first y? If there is no actual way maybe it should be emphasized, as it can be surprising.

3. "Odoc_examples.Scope" should be "Odoc_examples.Scope". This seems to be an odoc issue as the source seems legit: {!Odoc_examples.Scope}
4. In Section and Headings nothing is said about level-6 headings (contrary to all other headings)

Page Features

5. In the end of Module type of, M' should link to M' instead of to M

Page ocamldoc_differences

6. In "Odoc for authors", it is said that

There are no differences in how odoc handles comment placement between .ml and .mli files, which is another difference from OCamldoc.

However, this difference is not listed in the ocamldoc_differences

Conclusion

I can try to make the related PR, but I would need help sorting points 2, 3 and 4.

Otherwise, the doc was very clear and pleasant to read, thanks!

[Julow]

Thanks for the review !

About points 2, 3, 4:

2. The reference to the other y is {!Scope.y}. Additionally, the comment in A is also rendered into the parent page, it is the synopsis of the module. I think it would be worth adding an empty comment at the top to avoid this behavior, which is confusing when the comment talks about its own position.

3. This seems like a bug indeed, perhaps in the HTML backend. But more importantly, the reference is not resolving.

4. That's because there is no level 6 ! Also, the level 0 is not for sections but for the page title. The example should be changed to {[1-5] text} and the sentence "0 is reserved for page titles for .mld files." removed because it is already well explained in the section about pages.

[sanette]

4. That's because there is no level 6 !

but the "doc for authors" says:

The syntax for declaring sections is as follows:

{[0-6] text}

[panglesd]

Most problems have been fixed.