Render documentation attached to includes

[Julow]

Fixes #645

Before, the attached documentation was removed and the synopsis from the includee top-comment was used instead. Now, the attached documentation is rendered entirely and the includee top-comment is not.

There is an exception, if there is no documentation attached to the include, we render the synopsis extracted from the includee top-comment, as before.

This is on top of #643 to avoid conflicts.

[Julow]

This is removed because there is a documentation attached but it renders to nothing.
Some elements don't render to anything, for example @inline tags.

We could decide it's fine or we could add an exception for for elements that do not render ? cc @dbuenzli

Unrelated thought: Should we handle tags specifically ?
Currently, it's possible to have tags in the middle of a comment or in the middle of the preamble.
I don't see tags as markup elements like headings and paragraphs but as metadata attached directly to the declarations. I'd expect them on the same hierarchical level as the documentation text, not inside it.

[dbuenzli]

We could decide it's fine or we could add an exception for for elements that do not render ? cc @dbuenzli

I don't understand the question. Also:

Now, the attached documentation is rendered entirely and the includee top-comment is not.

The top-comment may already have docs, e.g. headings and paragraphs, I think you want these rendered. Did you want to say that you drop the preamble ?

I don't want to sound like a broken record but I think the only way to get to a consistent system is to think about these things in terms of synopse, preamble and content, not in terms of comments.

I don't see tags as markup elements like headings and paragraphs but as metadata attached directly to the declarations. I'd expect them on the same hierarchical level as the documentation text, not inside it.

That would be my understanding as well. But:

I don't see tags as markup elements like headings and paragraphs but as metadata attached directly to the declarations.

They are still placed by end-users as they see it fit so I think we should consider them as block-level stuff (and consecutive sequences of tags should define a single block, not done yet see #607)

[Julow]

On a regular declaration the preamble would be the tag then the paragraph but we agreed in #645 that includes are different, there is no preamble ever generated, we either take the decl comment entirely or make a synopsis from T's top-comment.

The problem I'm mentioning is that in this case:

module type T = sig
  (** Top-comment of T. *)
end

include T
(** @inline *)

the decl comment renders to nothing but is not technically empty so we won't attempt to take the synopsis out of T. Potential fixes:

• Decide it's OK
• Consider tags targeted at Odoc are not part of the doc (they are not rendered currently but are part of the markup: canonical, inline, open, closed)
• Handle tags at a different level and render them separately (eg. always after the documentation, wherever they are placed by the user). Like the previous point but applies to every tags and changes the layout.

[dbuenzli]

• Consider tags targeted at Odoc are not part of the doc (they are not rendered currently but are part of the markup: canonical, inline, open, closed)

Ah yes thanks for the clarifification. I'd say that this is the right idea.

[Drup]

The document part of the code looks ok to me.

[Drup]

Is first_to_ir still use after that ?

[Julow]

No, it's removed.

[Julow]

I've removed the fallback of rendering the synopsis extracted from the expansion when there is no doc attached to the include. We decided it doesn't made much sense during the last meeting.

[dbuenzli]

I would still suggest to only drop the synopsis and preamble, not the whole top comment. But I won't insist…

[Julow]

The top-comment from the included module type is dropped entirely. Do you suggest including it but cutting out some bits ?
The current way of choosing what is included or not (when writing the module type) is to add a floating comment after the top-comment.

[dbuenzli]

The top-comment from the included module type is dropped entirely. Do you suggest including it but cutting out some bits ?

I'm suggesting dropping both the synopsis and the preamble and including everything that comes after the preamble.

The current way of choosing what is included or not (when writing the module type) is to add a floating comment after the top-comment.

The problem is that most people writing these comments won't be aware of that. Namely to most persons writing M (who may not even think they will be included) the following two things will be the same because effectively they render to the same thing:

module M : sig 
(** Synopsis 

    Preamble 

    {1:prims Primitive functions} *) 

  val f : …
  (** [f] is *)
end

module M : sig
  (** Synopsis 

      Preamble *)

  (** {1:prims Primitive functions} *) 

  val f : …
  (** [f] is *)
end

However that will result in two different inclusions for the person who includes – who is likely not the same person.

In other words if the person who includes looks at the rendering of M she cannot predict what she will get on inclusion which I personally find undesirable.

[Julow]

What you are suggesting is consistent with the "stop the preamble at the first heading" rule. A generalization might be that if there is a heading in the top-comment, that heading and everything after it is treated as an extra floating comment.

The problem is that most people writing these comments won't be aware of that.

I don't agree with this. I wouldn't have expected one solution more likely than the other. After learning how comments are attached, I would absolutely expect the first and second comments to be handled differently.
Also, being able to split the "documentation before any item" into two comments is useful to have control over the preamble, what would be included, where the TOC is inserted.

[dbuenzli]

I don't agree with this. I wouldn't have expected one solution more likely than the other. After learning how comments are attached, I would absolutely expect the first and second comments to be handled differently.

That's a bit besides the point I'm making which is from the point of the person who includes. Of course it's always possible to be subtle, but subtle doesn't necessarily make things usable.

In practice people are not going to look at the comment structure of the things they include, especially since these may not be their libraries. For example when I include String I'm not going to dig out the ocaml source to look for what is going to happen. I'm going to look at the stdlib doc rendering. So I suggest to design for a user experience that allows to discover what will happen by looking at that.

So if you want least surprise and least bug reports of the form "this is not expected" for odoc I suggest to follow the rendering point of view point which in turn is consistent with the synopsis and preamble definition.