Assertion failed in doc-ock

[aantron]

Do:

• opam install odoc.1.2.0
• opam install tensorflow.0.0.10
• odoc compile `opam config var prefix`/lib/tensorflow/fnn/tensorflow_fnn__Fnn.cmt --package foo

the result is:

odoc: internal error, uncaught exception:
      File "src/docOckCmi.ml", line 355, characters 21-27: Assertion failed
      Raised at file "src/docOckCmi.ml", line 355, characters 21-33
      Called from file "src/docOckCmt.ml", line 53, characters 22-63
      Called from file "src/docOckCmt.ml", line 87, characters 4-41
      Called from file "list.ml", line 88, characters 24-34
      Called from file "src/docOckCmt.ml", line 94, characters 4-336
      Called from file "src/docOckCmt.ml", line 503, characters 25-62
      Called from file "list.ml", line 88, characters 24-34
      Called from file "src/docOckCmt.ml", line 501, characters 4-136
      Called from file "src/docOckCmt.ml", line 357, characters 38-69
      Called from file "src/docOckCmt.ml", line 412, characters 22-60
      Called from file "src/docOckCmt.ml", line 460, characters 16-51
      Called from file "src/docOckCmt.ml", line 503, characters 25-62
      Called from file "list.ml", line 88, characters 24-34
      Called from file "src/docOckCmt.ml", line 501, characters 4-136
      Called from file "src/docOckCmt.ml", line 510, characters 14-46
      Called from file "src/docOck.ml", line 150, characters 31-75
      Called from file "lib/compile.ml", line 21, characters 8-17
      Called from file "src/cmdliner_term.ml", line 27, characters 19-24
      Called from file "src/cmdliner.ml", line 106, characters 32-39

The relevant code seems to be:

https://github.com/ocaml-doc/doc-ock/blob/ae76154f6d7651f03d888ff1363092d5751a2e0b/src/docOckCmi.ml#L348-L360

I also observed this being raised by aws-s3/aws_s3__S3.cmt from aws-s3.

[lpw25]

Which version of OCaml? That assertion really shouldn't be reachable, it may suggest a bug in the type-checker.

[aantron]

I just reproduced it on 4.04.2 using the above instructions. Please do let me know if any other info is missing.

I am seeing a similar assertion failure using ocaml 4.06.1+flambda and odoc 1.2.0 when I run jbuilder build @doc on my project.

odoc: internal error, uncaught exception:
      File "src/docOckCmti.ml", line 431, characters 17-23: Assertion failed

This seems to be fixed now, or at least the version that I encountered above.

[aantron]

@lpw25, it's failing on the optional argument on this line: https://github.com/LaurentMazare/tensorflow-ocaml/blob/5df027d51b433c08b6540484033166783bd24c22/src/fnn/fnn.ml#L533.

?(addn_inputs : (Input_id.t * (float, b) Tensor.t) list option)

The failing code is now here in odoc:

odoc/src/loader/cmi.ml

Lines 369 to 375 in ab4b893

	if Btype.is_optional lbl then
	match (Btype.repr arg).desc with
	| Tconstr(path, [arg], _)
	when OCamlPath.same path Predef.path_option ->
	read_type_expr env arg
	| _ -> assert false
	else read_type_expr env arg

It looks like Predef.path_option is the built-in, plain option, but option in tensorflow is shadowed by Base.option. The path odoc gets is Base.option. The comparison fails, failing the pattern guard, and triggering the assertion failure.

[aantron]

I suspect the fix is something like taking only the last component of the path for comparison with option. This is assuming the OCaml compiler checks for literal option only when checking the annotation, which I haven't verified. If you can confirm this off the top of your head, I can make the fix.

[lpw25]

Ok, this is a bug in the OCaml type printer that I've copied into odoc:

        OCaml version 4.04.2

# type 'a opt = 'a option;;
type 'a opt = 'a option

# let foo (type a) ?(x : a opt) () = ();;
val foo : ?x:<hidden> -> unit -> unit = <fun>

I suspect the code was fine before GADTs were added, since the type checker is quite careful to force the type to use Predef.path_option, but unification is now more complicated and it seems that in some cases the path can be changed. It's actually not trivial to produce a complete fix that allows us to always find the right type because of things like:

type 'a opt = int option;;
type 'a opt = int option
#   let foo (type a) ?(x : a opt) () = ();;
val foo : ?x:<hidden> -> unit -> unit = <fun>

so for now the best thing to do is probably to replace the assert false with something similar to the <hidden> used by the type printer, so at least we still produce some output.

[lpw25]

I've reported the bug upstream:

https://caml.inria.fr/mantis/view.php?id=7866