odoc: several variants completely missing from generated docs, but present in .odocl

[edwintorok]

The documentation for Omd's type block is incorrect.

type !'attr block = 
| Blockquote of 'attr4 * 'attr5 [block](https://ocaml.org/p/omd/latest/doc/Omd/index.html#type-block) list
| Thematic_break of 'attr6
| Code_block of 'attr9 * string * string
| Html_block of 'attr10 * string
| Definition_list of 'attr11 * 'attr12 [def_elt](https://ocaml.org/p/omd/latest/doc/Omd/index.html#type-def_elt) list

However the source code has:

 type 'attr block =
    | Paragraph of 'attr * 'attr C.t
    | List of 'attr * list_type * list_spacing * 'attr block list list
    | Blockquote of 'attr * 'attr block list
    | Thematic_break of 'attr
    | Heading of 'attr * int * 'attr C.t
    | Code_block of 'attr * string * string
    | Html_block of 'attr * string
    | Definition_list of 'attr * 'attr def_elt list
    | Table of 'attr * ('attr C.t * cell_alignment) list * 'attr C.t list list
        (** A table is represented by a header row, which is a list of pairs of
            header cells and alignments, and a list of rows *)

Same issue with older version of API docs: https://ocaml.github.io/omd/omd/Omd/index.html#type-block

What I tried:

• adding a new variant at the beginning, e.g. Z: it shows up, even though Paragraph and List and Table do not
• removing the extra doc comment for table, doesn't help
• look at the .odocl file with strings -a
• generate other output formats: html-generate, latex-generate, man-generate are all affected

Steps to reproduce:

opam source omd
dune build @doc --cache=disabled
odoc latex-generate _build/default/_doc/_odocls/omd/omd.odocl --output-dir tmp
strings -a _build/default/_doc/_odocls/omd/omd.odocl|grep -A30 %attr1
cat tmp/omd/Omd.3o|grep -A20 'type.*attr block'

Output for strings -a, see that the variants are all present:

%attr1@@@
%block
W3t_block.r_Omd.p_omd@@@
$attr@A@@
*)Paragraph
        "ctor_Paragraph.t_block.r_Omd.p_omd@
%attr0
%attr1@@@
D$List
c=ctor_List.t_block.r_Omd.p_omd@
%attr2
%attr3@@@@@
v*Blockquote
]       #ctor_Blockquote.t_block.r_Omd.p_omd@
%attr4
%attr5@@@@
.Thematic_break
@       'ctor_Thematic_break.t_block.r_Omd.p_omd@
%attr6@@
'Heading
         ctor_Heading.t_block.r_Omd.p_omd@
%attr7
%attr8@@@
*Code_block
        #ctor_Code_block.t_block.r_Omd.p_omd@
%attr9
&string
3,coret_string@
        @@@
*Html_block
4)      #ctor_Html_block.t_block.r_Omd.p_omd@
&attr10
/Definition_list
F       (ctor_Definition_list.t_block.r_Omd.p_omd@
&attr11
&attr12@@@@
%Table
.>ctor_Table.t_block.r_Omd.p_omd

Output for man-generate, see that List, Paragraph and Table are missing:

\f[CB]type\fR !'attr block = 
.br 
.ti +2
| \f[CB]Blockquote\fR \f[CB]of\fR \f[CB]'attr4\fR * \f[CB]'attr5\fR block list
.br 
.ti +2
| \f[CB]Thematic_break\fR \f[CB]of\fR \f[CB]'attr6\fR
.br 
.ti +2
| \f[CB]Code_block\fR \f[CB]of\fR \f[CB]'attr9\fR * string * string
.br 
.ti +2
| \f[CB]Html_block\fR \f[CB]of\fR \f[CB]'attr10\fR * string
.br 
.ti +2
| \f[CB]Definition_list\fR \f[CB]of\fR \f[CB]'attr11\fR * \f[CB]'attr12\fR def_elt list
.br 
.sp 
\f[CB]type\fR attributes = (string * string) list
.sp 
\f[CB]type\fR doc = attributes block list

[edwintorok]

It looks like all variants that have C.t as part of its type argument are missing.

[jonludlam]

Can you find the module C in the produced docs? Odoc will hide stuff that it believes should be hidden.

[jonludlam]

Oh hang on I can do this myself :-)

[jonludlam]

OK so the problem is that odoc doesn't know where to find the types inline, list_type, list_spacing and cell_alignment in the generated docs - it only knows of their locations in the hidden modules Omd__Ast_inline or Omd__Ast_block. Normally dune builds the wrapper module with all of the aliases marked with canonical tags, but in this case the wrapper module is hand written, so odoc can't quite figure out where they are. One solution is to mark the types with explicit canonical tags so odoc knows where to find them. See ocaml-community/omd#307

[edwintorok]

Hmm even if it cannot find the types to link them, showing the variant entry would be better, or print some warning during the build that it has dropped the variants.

That way we could find other instances of this bug in other packages.

[jonludlam]

Totally agree with the warning. I think also we need to adjust what we do after emitting the warning too, though whether we show all variants or drop them all and render it as an opaque type I'm not sure yet.

[jonludlam]

This should be 'fixed' now - we should have a warning, but all the variants should be rendered.