1

I'm getting ocamldoc warnings:

Warning: Element MyModule.VariantName not found

when using {!MyModule.VariantName} in doc comments.

The ocamldoc doc says

In this chapter, we use the word element to refer to any of the following parts of an OCaml source file: a type declaration, a value, a module, an exception, a module type, a type constructor, a record field, a class, a class type, a class method, a class value or a class inheritance clause.

and later when explaining text formatting:

∣ {! string }  insert a reference to the element named string. string must be a fully qualified element name, for example Foo.Bar.t. The kind of the referenced element can be forced (useful when various elements have the same qualified name) with the following syntax: {! kind : string } where kind can be module, modtype, class, classtype, val, type, exception, attribute, method or section.

Can I reference a type constructor using {! string }?

How do the first group of kinds of elements relate to the second group of kinds of elements?

Mike Samuel
  • 118,113
  • 30
  • 216
  • 245

1 Answers1

3

After looking at the implementation, it looks like it is possible to refer to a variant constructor, but with a rather weird syntax: you must use the {!typename.constrname} syntax or, from another module, {!Modulename.typename.constrname}. With the code example below, that would by {!mylist.Cons} for example. This will generate a hyperlink, but unfortunately the text will still be typename.constrname and not just refer to the constructor name itself.

(I also learned that there is an "explicit" way to tell ocamldoc to which syntactic category the mentioned identifier belong, I suppose to help in some ambiguous case. So just as you could use either {!mylist} or {!type:mylist} to denote a type constructor, you can use either {!mylist.Nil} or {!const:mylist.Nil} to denote the variant constructor.)

Vocabulary note: In the type declaration

type 'a mylist =
| Nil
| Cons of 'a * 'a mylist

the names Nil and Cons are not called "type constructors", but only "constructors" or "variant constructors". The type constructors are the names of parametrized types (or non-parametrized, for constant type constructors) living at the type rather than the value level, mylist in this example.

gasche
  • 31,259
  • 3
  • 78
  • 100
  • Ah. Thanks for explaining the terminology. So the two pieces of documentation are not inconsistent in this regard. I was mistakenly assuming that `MyModule.MyVariantName` was an element by the first definition. – Mike Samuel May 24 '13 at 21:20
  • 1
    @MikeSamuel: I had an in-depth look at how the thing works, and it appears it is actually possible. – gasche May 24 '13 at 22:06