package doc-ock

  1. Overview
  2. Docs
package doc-ock
Legend:
Library
Module
Module type
Parameter
Class
Class type

This is an interface with all of the module system features.

This text is centered.

This text is left-aligned.

This text is right-aligned.

This documentation demonstrates:

  • comment formatting
  • unassociated comments
  • documentation sections

  • module system documentation including

    1. submodules
    2. module aliases
    3. module types
    4. module type aliases
    5. modules with signatures
    6. modules with aliased signatures

A numbered list:

  1. 3
  2. 2
  3. 1

David Sheets is the author.

  • author David Sheets

You may find more information about this HTML documentation renderer at github.com/dsheets/ocamlary.

This is some verbatim text: 

verbatim

This is some verbatim text: 

[][df[]]}}

Here is some raw LaTeX: $e^{i\pi} = -1$

Here is an index table of Empty modules:

Here is a table of links to indexes: indexlist

Here is some superscript: x2

Here is some subscript: x0

Here are some escaped brackets: { [ @ ] }

Here is some emphasis followed by code.

An unassociated comment

Level 0

Level 1

Level 2

Level 3

Level 4
Level 5
Level 6
Level 7
Level 8
Level 9

Basic module stuff

module Empty : sig ... end

A plain, empty module

module type Empty = sig ... end

An ambiguous, misnamed module type

module type MissingComment = sig ... end

An ambiguous, misnamed module type

Level 9000
module EmptyAlias = Empty

A plain module alias of Empty

EmptySig

module type EmptySig = sig ... end

A plain, empty module signature

module type EmptySigAlias = EmptySig

A plain, empty module signature alias of

A plain module of a signature of EmptySig (reference)

A plain module with an alias signature

module One : sig ... end
module type SigForMod = sig ... end

There's a signature in a module in this signature.

module type SuperSig = sig ... end

For a good time, see subSig or subSig or SuperSig.EmptySig. Section Level 9000 is also interesting. EmptySig is a general reference but EmptySig is the section and EmptySig is the module signature.

module Buffer : sig ... end

Buffer.t

Some text before exception title.

Basic exception stuff

After exception title.

exception Kaboom of unit

Unary exception constructor

exception Kablam of unit * unit

Binary exception constructor

exception Kapow of unit * unit

Unary exception constructor over binary tuple

exception EmptySig

EmptySig is general but EmptySig is a module and EmptySig is this exception.

exception EmptySigAlias

EmptySigAlias is this exception.

Basic type and value stuff with advanced doc comments

type ('a, 'b) a_function = 'a -> 'b

a_function is general but a_function is this type and a_function is the value below.

val a_function : x:int -> int

This is a_function with param and return type.

  • parameter x

    the x coordinate

  • returns

    the y coordinate

val fun_fun_fun : ((int, int) a_function, (unit, unit) a_function) a_function
val fun_maybe : ?yes:unit -> unit -> int
val not_found : unit -> unit
  • raises Not_found

    That's all it does

val ocaml_org : string
val some_file : string
  • see some_file

    The file called some_file

val some_doc : string
  • see some_doc

    The document called some_doc

val since_mesozoic : unit

This value was introduced in the Mesozoic era.

  • since mesozoic
val changing : unit

This value has had changes in 1.0.0, 1.1.0, and 1.2.0.

  • before 1.0.0

    before 1.0.0

  • before 1.1.0

    before 1.1.0

  • version 1.2.0
val with_foo : unit

This value has a custom tag foo. @foo the body of the custom foo tag

Some Operators

val (~-) : unit
val (!) : unit
val (@) : unit
val ($) : unit
val (%) : unit
val (^) : unit
val (&) : unit
val (*) : unit
val (-) : unit
val (+) : unit
val (<) : unit
val (>) : unit
val (-?) : unit
val (/) : unit
val (-|) : unit
val (:=) : unit
val (=) : unit
val (land) : unit

Advanced Module Stuff

module CollectionModule : sig ... end

This comment is for CollectionModule.

module type COLLECTION = module type of CollectionModule

module type of

module Recollection (C : COLLECTION) : COLLECTION with type collection = C.element list and type element = C.collection
module type MMM = sig ... end
module type RECOLLECTION = MMM with module C = Recollection(CollectionModule)
module type RecollectionModule = sig ... end
module type A = sig ... end
module type B = sig ... end
module type C = sig ... end

This module type includes two signatures.

module FunctorTypeOf (Collection : module type of CollectionModule) : sig ... end

This comment is for FunctorTypeOf.

module type IncludeModuleType = sig ... end

This comment is for IncludeModuleType.

module type ToInclude = sig ... end
include ToInclude
module IncludedA : sig ... end
module type IncludedB = sig ... end

Advanced Type Stuff

type record = {
  1. field1 : int;
    (*

    This comment is for field1.

    *)
  2. field2 : int;
    (*

    This comment is for field2.

    *)
}

This comment is for record.

This comment is also for record.

type mutable_record = {
  1. mutable a : int;
    (*

    a is first and mutable

    *)
  2. b : unit;
    (*

    b is second and immutable

    *)
  3. mutable c : int;
    (*

    c is third and mutable

    *)
}
type universe_record = {
  1. nihilate : 'a. 'a -> unit;
}
type variant =
  1. | TagA
    (*

    This comment is for TagA.

    *)
  2. | ConstrB of int
    (*

    This comment is for ConstrB.

    *)
  3. | ConstrC of int * int
    (*

    This comment is for binary ConstrC.

    *)
  4. | ConstrD of int * int
    (*

    This comment is for unary ConstrD of binary tuple.

    *)

This comment is for variant.

This comment is also for variant.

type poly_variant = [
  1. | `TagA
    (*

    This comment is for `TagA.

    *)
  2. | `ConstrB of int
    (*

    This comment is for `ConstrB.

    *)
]

This comment is for poly_variant.

Wow! It was a polymorphic variant!

type (_, _) full_gadt =
  1. | Tag : (unit, unit) full_gadt
  2. | First : 'a -> ('a, unit) full_gadt
  3. | Second : 'a -> (unit, 'a) full_gadt
  4. | Exist : 'a * 'b -> ('b, unit) full_gadt

This comment is for full_gadt.

Wow! It was a GADT!

type 'a partial_gadt =
  1. | AscribeTag : 'a partial_gadt
  2. | OfTag of 'a partial_gadt
  3. | ExistGadtTag : ('a -> 'b) -> 'a partial_gadt

This comment is for partial_gadt.

Wow! It was a mixed GADT!

type _ record_arg_gadt =
  1. | With_rec : {
    1. foo : int;
    } -> unit record_arg_gadt
  2. | With_poly_rec : {
    1. bar : 'a. 'a -> 'a;
    } -> ('a -> 'a) record_arg_gadt

This comment is for record_arg_gadt.

Wow! It was a GADT with record arguments

type alias = variant

This comment is for alias.

type tuple = (alias * alias) * alias * (alias * alias)

This comment is for tuple.

type variant_alias = variant =
  1. | TagA
  2. | ConstrB of int
  3. | ConstrC of int * int
  4. | ConstrD of int * int

This comment is for variant_alias.

type record_alias = record = {
  1. field1 : int;
  2. field2 : int;
}

This comment is for record_alias.

type poly_variant_union = [
  1. | poly_variant
  2. | `TagC
]

This comment is for poly_variant_union.

type 'a poly_poly_variant = [
  1. | `TagA of 'a
]
type ('a, 'b) bin_poly_poly_variant = [
  1. | `TagA of 'a
  2. | `ConstrB of 'b
]
type 'a open_poly_variant = [> `TagA ] as 'a
type 'a open_poly_variant2 = [> `ConstrB of int ] as 'a
type 'a open_poly_variant_alias = 'a open_poly_variant open_poly_variant2
type 'a poly_fun = [> `ConstrB of int ] as 'a -> 'a
type 'a poly_fun_constraint = 'a -> 'a constraint 'a = [> `TagA ]
type 'a closed_poly_variant = [< `One | `Two ] as 'a
type 'a clopen_poly_variant = [< `One | `Two of int | `Three Two Three ] as 'a
type nested_poly_variant = [
  1. | `A
  2. | `B of [ `B1 | `B2 ]
  3. | `C
  4. | `D of [ `D1 of [ `D1a ] ]
]
type ('a, 'b) full_gadt_alias = ('a, 'b) full_gadt =
  1. | Tag : (unit, unit) full_gadt_alias
  2. | First : 'a -> ('a, unit) full_gadt_alias
  3. | Second : 'a -> (unit, 'a) full_gadt_alias
  4. | Exist : 'a * 'b -> ('b, unit) full_gadt_alias

This comment is for full_gadt_alias.

type 'a partial_gadt_alias = 'a partial_gadt =
  1. | AscribeTag : 'a partial_gadt_alias
  2. | OfTag of 'a partial_gadt_alias
  3. | ExistGadtTag : ('a -> 'b) -> 'a partial_gadt_alias

This comment is for partial_gadt_alias.

exception Exn_arrow : unit -> exn

This comment is for Exn_arrow.

type mutual_constr_a =
  1. | A
  2. | B_ish of mutual_constr_b
    (*

    This comment is between mutual_constr_a and mutual_constr_b.

    *)

This comment is for mutual_constr_a then mutual_constr_b.

and mutual_constr_b =
  1. | B
  2. | A_ish of mutual_constr_a
    (*

    This comment must be here for the next to associate correctly.

    *)

This comment is for mutual_constr_b then mutual_constr_a.

type rec_obj = < f : int ; g : unit -> unit ; h : rec_obj >
type 'a open_obj = < f : int ; g : unit -> unit.. > as 'a
type 'a oof = < a : unit.. > as 'a -> 'a
type 'a any_obj = < .. > as 'a
type empty_obj = < >
type one_meth = < meth : unit >
type ext = ..

A mystery wrapped in an ellipsis

type ext +=
  1. | ExtA
type ext +=
  1. | ExtB
type ext +=
  1. | ExtC of unit
  2. | ExtD of ext
type ext +=
  1. | ExtE
type ext += private
  1. | ExtF
type 'a poly_ext = ..

'a poly_ext

type poly_ext +=
  1. | Foo of 'b
  2. | Bar of 'b * 'b
    (*

    'b poly_ext

    *)
type poly_ext +=
  1. | Quux of 'c
    (*

    'c poly_ext

    *)
module ExtMod : sig ... end
type ExtMod.t +=
  1. | ZzzTop0
    (*

    It's got the rock

    *)
type ExtMod.t +=
  1. | ZzzTop of unit
    (*

    and it packs a unit.

    *)
val launch_missiles : unit -> unit

Rotate keys on my mark...

type my_mod = (module COLLECTION)

A brown paper package tied up with string

class empty_class : object ... end
class one_method_class : object ... end
class two_method_class : object ... end
class 'a param_class : 'a -> object ... end
type my_unit_object = unit param_class
type 'a my_unit_class = unit param_class as 'a
module Dep1 : sig ... end
module Dep2 (Arg : sig ... end) : sig ... end
type dep1 = Dep2(Dep1).B.c
module Dep3 : sig ... end
module Dep4 : sig ... end
module Dep5 (Arg : sig ... end) : sig ... end
type dep2 = Dep5(Dep4).Z.X.b
type dep3 = Dep5(Dep4).Z.Y.a
module Dep6 : sig ... end
module Dep7 (Arg : sig ... end) : sig ... end
type dep4 = Dep7(Dep6).M.Y.d
module Dep8 : sig ... end
module Dep9 (X : sig ... end) : sig ... end
module type Dep10 = Dep9(Dep8).T with type t = int
module Dep11 : sig ... end
module Dep12 (Arg : sig ... end) : sig ... end
type dep5 = Dep13.c
module type With1 = sig ... end
module With2 : sig ... end
module With3 : With1 with module M = With2
type with1 = With3.N.t
module With4 : With1 with module M := With2
type with2 = With4.N.t
module With5 : sig ... end
module With6 : sig ... end
module With7 (X : sig ... end) : sig ... end
module type With8 = With7(With6).T with module M = With5 and type M.N.t = With5.N.t
module With9 : sig ... end
module With10 : sig ... end
module type With11 = With7(With10).T with module M = With9 and type N.t = int
module type NestedInclude1 = sig ... end
include NestedInclude1
module type NestedInclude2 = sig ... end
include NestedInclude2 with type nested_include = int
type nested_include = int
module DoubleInclude1 : sig ... end
module DoubleInclude3 : sig ... end
include module type of DoubleInclude3.DoubleInclude2
type double_include
module IncludeInclude1 : sig ... end
include module type of IncludeInclude1
module type IncludeInclude2 = sig ... end
include IncludeInclude2
type include_include

Trying the {!modules: ...} command.

With ocamldoc, toplevel units will be linked and documented, while submodules will behave as simple references.

With odoc, everything should be resolved (and linked) but only toplevel units will be documented.

Weirder usages involving module types

  • IncludeInclude1.IncludeInclude2
  • Dep4.T
  • A.Q

Playing with @canonical paths

module CanonicalTest : sig ... end
val test : 'a CanonicalTest.Base__.List.t -> unit

Some ref to CanonicalTest.Base__Tests.C.t and CanonicalTest.Base__Tests.L.id. But also to CanonicalTest.Base__.List and CanonicalTest.Base__.List.t

Aliases again

module Aliases : sig ... end

Let's imitate jst's layout.

Section title splicing

I can refer to

But also to things in submodules:

  • {!section:SuperSig.SubSigA.subSig} : subSig
  • {!Aliases.incl} : incl

And just to make sure we do not mess up:

  • {{!section:indexmodules}A} : A
  • {{!aliases}B} : B
  • {{!section:SuperSig.SubSigA.subSig}C} : C
  • {{!Aliases.incl}D} : D

New reference syntax

module type M = sig ... end
module M : sig ... end

Here goes:

  • {!M.t} : M.t
  • {!module-M.t} : M.t
  • {!module-type-M.t} : M.t
module Only_a_module : sig ... end

Some here should fail:

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct