Inline sub module documentation with odoc

Learning
1

Hello!

I was wondering if sub module’s documentation could be
inlined into the general module documentation.

For example I have my main documentation’s page:

(* A.mli *)

module B : sig
  (** Some documentation about a wonderful function *)
end

But the documentation of B is a redirection to another html page.
Would there be a way to inline that other html page?

I suspect (** @inline *) should be used but I did not manage
to get my expected result with this last.

1 Like
2

I believe it is not possible (yet): Support inlining expansions in their parent's page · Issue #564 · ocaml/odoc · GitHub

2 Likes
3

Personally I wish it remained so. From an end-user perspective the structural regularity of generated docs is more important. Leaving these things to the producer’s tastes is not such a good idea.

5

I don’t especially agree,
I’m thinking of the library: data-encoding. The main module data_encoding.mli provides multiple utilities, but they kind all depend on a sub-module Encoding .
The whole library works only because of that sub module and its documentation is as much important as the library entry point documentation.

6

I have come around to agreeing with this. For awhile I also wanted this feature, but I think it’s more valuable to be consistent.

For the sake of argument, though, I generated odoc output for an incomplete, work-in-progress 9P2000 library that I work on from time to time.

https://droyo.srht.site/_odoc/styx/Styx/Proto/index.html#module-Tversion

Here, I defined one module per protocol message. Each 9P message typically has 0-3 fields that are unique to that message, so initially I wanted to expand the sub-module documentation into this parent page, and only document the unique fields. The common fields could have been documented elsewhere. I thought it would be nicer if readers could see the signatures and docs on the same page.

7

Looking at the generate docs for this module (https://docs.ocaml.pro/html/LIBRARY.data_encoding@data-encoding.0.2/Data_encoding/index.html), it looks pretty good to me; the Encoding module signature is quite large and warrants its own page, in my opinion. Ocamldoc comments for the module itself could be added to summarize it and describe its importance, and those would appear in the parent module’s page.

8

@vch9 I’m not saying you won’t be able to find examples where the feature makes sense.

The problem is that everyone will have a different definition of what is small, or some will have the impression that it’s always better to inline everything regardless of the size of the module. So in aggregate docsets like those generated by odig for your opam switches, you get an unpredictable structure for end users (starting with the hackability of URLs).

Now someone of course will say oh but you should be able to override it on the cli of odoc but that’s not good either because the way you write your docs does depend on the structure of the output, so you don’t want to be betrayed by it later.