First heading not included in TOC

[rizo]

If the interface documentation starts with a heading (like {1 ...}) and that heading is the first doc item in the interface the heading is not included in the TOC.

This was reported by @c-cube and observed in Containers where modules start with a heading (e.g. CCArray).

The general recommendation is to start an interface documentation with a short sentence/paragraph, but this bug should be fixed anyway.

[c-cube]

for the context, back when I used ocamldoc the same headers gave this kind of TOC: https://simon.cedeela.fr/ocaml-containers/1.0/

[aantron]

@c-cube and @rizo, I think you are talking about different TOCs.

@c-cube: I believe you are referring to the module listing of a library. Currently, we are generating no summaries there at all. I think Dune does that for now, anyway, not odoc. We probably can't fix that in the very near term. I think this is what @c-cube would actually like fixed, however.

@rizo: I believe you are referring to the in-page TOC in a single module. Headings from the top comment (of any level, no matter where they appear in the top comment) are not being included in that TOC. I'll fix that soon.

[aantron]

I remembered why section headings in the top comment don't go into the table of contents.

The top comment is supposed to be introductory/summary material, and the table of contents is displayed below it when it is displayed inline (for example, at narrow screen widths). For comparison, see a typical Wikipedia article.

(** Module summary, first sentence will eventually go into the module index.

    {1 This section does not go into the in-page TOC}

    In fact, the heading shouldn't be here, because this whole comment is supposed
    to be brief introductory material. *)

(** {1 This section does go into the in-page TOC}

    The TOC is inserted immediately above the rendering of this comment. *)

Perhaps we should emit a warning about this.

[dbuenzli]

@aantron In the wikipedia article the top heading is at a different heading level. In our case this is the module name which is heading 0 which should not not go in the toc.

I don't think there's any need for warnings or opinions here. It's better to have a simple and predictable system, simply include any heading level 1 in the toc wherever these happen to occur.

[aantron]

I'm indeed going to make the change to put all the headings (other than the title) into the TOC, but first a couple more points of discussion about the warning/position of the TOC :)

• What I meant is that the text immediately under the top heading never has any additional headings in it on Wikipedia (AFAIU).
• On the matter of being predictable, there is a different way in which not discouraging headings in that top comment is unpredictable. If the typical author is reviewing their docs with in a wide window (the typical case), they may not realize where the TOC appears when it is displayed inline (after the top comment). So, they might not realize that there is an important presentation difference between putting a heading into the top comment, and putting it into a separate comment.

It seems useful to warn authors about headings in order to make them aware of this.

Another possibility is to change where odoc generates the TOC, so that if there is a heading in the top comment, the TOC is rendered before that heading. Otherwise, it is rendered at the end of the top comment, as done unconditionally now.

[dbuenzli]

Actually @aantron I would have expected the toc to be in div separate from the content.

[c-cube]

I was indeed referring to the toplevel {1 heading} to occur in the library list of modules. OCamldoc has done it for a long time and I think imitating ocamldoc on that is predictable (and useful) enough.

[aantron]

@dbuenzli Where do you think the TOC should be in the markup? It is currently separate from the rest of the content in that it is in its own element, but not in the sense that it doesn't appear in between content (the top comment and the rest of the content, of course).

@c-cube Indeed, we want to imitate ocamldoc in that.

[dbuenzli]

@aantron I had a look at the generated markup and it seems to me that what is done now is sensitive --- in the sense that it seems to be at the right place for wikipedia style inline toc and it is properly classified which allows to rearrange things e.g. via css-grid.

But I still don't understand what the problem with this:

• On the matter of being predictable, there is a different way in which not discouraging headings in that top comment is unpredictable. If the typical author is reviewing their docs with in a wide window (the typical case), they may not realize where the TOC appears when it is displayed inline (after the top comment). So, they might not realize that there is an important presentation difference between putting a heading into the top comment, and putting it into a separate comment.

is. Basically an author who hasn't a summary comment in the toplevel ends up with doc that looks like:

module M 
toc
first heading

and I don't really see why there's a need to warn about this. Unless the way you are now processing would entail:

module M 
first heading
toc 

But I would rather qualify that as a bug. It's not what is in the top comment that should come before the toc it's any sequence of documentation comments before the first header and/or structure item.

[aantron]

What I mean is that if...

1. we silently put headings from the top comment into the TOC:

   (** This module does XYZ
   
        {2 Heading} <-- If we put this into the TOC *)
   
   (** {2 Other heading} *)
   

2. the author is viewing the output in a wide window (as normal on a desktop/laptop), where our CSS moves the TOC into the sidebar,

...then, the author will see that both Heading and Other heading are in the TOC, in the sidebar, and also look "normal" in the main "pane":

module M
Heading
Other heading

There is no reason for the author to think that there is a subtle difference between the positioning of Heading and Other heading.

However, if someone resizes the window so that the CSS moves the TOC "back" inline, they will have only the main pane, which suddenly has:

module M
Heading
TOC
Other heading

which authors are likely not to check (nor do I think it's reasonable to ask them to). Also, perhaps confusingly, this inline TOC will include a link back up to Heading, which also visually looks as if it includes the TOC in its section content.

So, we will have set it up so that Heading and Other heading are likely indistinguishable for the author under their normal workflow, but might have a different meaning for readers, depending on the window width they are reading at.

So, I suggest to include a warning, so that if Heading appears in the top comment, we inform the author that "This heading will be displayed before the table of contents in narrow windows, such as on mobile devices," and suggest to "break up the comment before the heading, so it does not appear in the first doc comment in the file."

We will then include the heading in the TOC anyway.

[dbuenzli]

So, I suggest to include a warning, so that if Heading appears in the top comment, we inform the author that "This heading will be displayed before the table of contents in narrow windows, such as on mobile devices," and suggest to "break up the comment before the heading, so it does not appear in the first doc comment in the file."

What I suggest is that this is a bug in odoc, the toc should be placed before the first heading. That is in the example:

(** This module does XYZ

     {1 Heading}

the heading should go in the toc and the rendering should be

module M 
This module does XYZ
TOC
Heading 
Other heading

It seems the current way of doing is attributing semantics to comments as units ("the top comment") but that's not the way the ocamldoc language works. For example for the ocamldoc the following two sequences are identical:

(** {1 Hey} *)
(** {1 Ho} *)

(** {1 Hey}
    {1 Ho} *)

You should not rely on something being "the first comment". So I'd say that the current way of operating is a bug in determining what is the module preamble is (i.e. what comes before the toc). A good definition for the module preamble would be any content (scattered among as many odoc comments it wishes) that comes before the first heading or structure item if there is no heading.

If you determine the module preamble that way there's no need for a warning.

[aantron]

Ok, that is what I'm suggesting above with

Another possibility is to change where odoc generates the TOC, so that if there is a heading in the top comment, the TOC is rendered before that heading. Otherwise, it is rendered at the end of the top comment, as done unconditionally now.

Modified with: it doesn't matter where the top comment ends. I'll change odoc to disregard comment breaks.