Docstrings(3)

💖 Docstrings — the OCaml library glow-up, bestie 💖

okay so this is Docstrings from the OCaml library (manual section 3, iykyk), and it's literally the module that handles documentation comments. Sit down, hydrate, and let's get into it 🫶

🌸 Module

Module Docstrings
 : sig end

Documentation comments. That's the whole vibe ✨

⚠️ Warning, and I mean it: this module is unstable and it's part of Compiler_libs. So like… it works, but it might change on you. Not me trusting it with my whole life 💀

val init : unit -> unit

(Re)Initialise all docstring state. Everything. Fresh start, main character reset 🦋

val warn_bad_docstrings : unit -> unit

Emit warnings for unattached and ambiguous docstrings. Basically the module's way of saying "bestie, this comment isn't attached to anything" 😭

---

🎀 Docstrings

type docstring

Documentation comments. The core type, the blueprint, the moment 💅

val docstring : string -> Location.t -> docstring

Create a docstring. Give it the text and a Location.t, done ✨

val register : docstring -> unit

Register a docstring. Put it on the official list 👑

val docstring_body : docstring -> string

Get the text of a docstring — the actual words, the body, the content 🍓

val docstring_loc : docstring -> Location.t

Get the location of a docstring. Where it lives, its address, its vibe check 🌈

---

🦋 Set functions

These functions are used by the lexer to associate docstrings to the locations of tokens. (Yes, the lexer. It's doing the most, respectfully 💜)

val set_pre_docstrings : Lexing.position -> docstring list -> unit

Docstrings immediately preceding a token.

val set_post_docstrings : Lexing.position -> docstring list -> unit

Docstrings immediately following a token.

val set_floating_docstrings : Lexing.position -> docstring list -> unit

Docstrings that are not immediately adjacent to a token. Floating. Untethered. Free spirits 🧚

val set_pre_extra_docstrings : Lexing.position -> docstring list -> unit

Docstrings immediately following the token which precedes this one. (yes, read that twice, I had to 😭)

val set_post_extra_docstrings : Lexing.position -> docstring list -> unit

Docstrings immediately preceding the token which follows this one.

---

🔥 Items

The Docstrings.docs type represents documentation attached to an item. This is the one you'll actually be hanging out with 🫶

type docs = {
 docs_pre : docstring option ;
 docs_post : docstring option ;
 }

val empty_docs : docs

val docs_attr : docstring -> Parsetree.attribute

val add_docs_attrs : docs -> Parsetree.attributes ->
Parsetree.attributes

Convert item documentation to attributes and add them to an attribute list. Glow-up: doc → attribute 💅

val symbol_docs : unit -> docs

Fetch the item documentation for the current symbol. Heads up: this also marks this documentation (for ambiguity warnings). It's a two-for-one, no cap.

val symbol_docs_lazy : unit -> docs Lazy.t

val rhs_docs : int -> int -> docs

Fetch the item documentation for the symbols between two positions. Also marks this documentation (for ambiguity warnings). Same deal, different range 📍

val rhs_docs_lazy : int -> int -> docs Lazy.t

val mark_symbol_docs : unit -> unit

Mark the item documentation for the current symbol (for ambiguity warnings). Just the marking, no fetching.

val mark_rhs_docs : int -> int -> unit

Mark as associated the item documentation for the symbols between two positions (for ambiguity warnings).

---

🌸 Fields and constructors

The Docstrings.info type represents documentation attached to a field or constructor. Different type, same energy ⭐

type info = docstring option

val empty_info : info

val info_attr : docstring -> Parsetree.attribute

val add_info_attrs : info -> Parsetree.attributes ->
Parsetree.attributes

Convert field info to attributes and add them to an attribute list.

val symbol_info : unit -> info

Fetch the field info for the current symbol.

val rhs_info : int -> info

Fetch the field info following the symbol at a given position.

---

🎀 Unattached comments

The Docstrings.text type represents documentation which is not attached to anything. Solitary. Independent. Living its truth 🙈

type text = docstring list

val empty_text : text

val empty_text_lazy : text Lazy.t

val text_attr : docstring -> Parsetree.attribute

val add_text_attrs : text -> Parsetree.attributes ->
Parsetree.attributes

Convert text to attributes and add them to an attribute list.

val symbol_text : unit -> text

Fetch the text preceding the current symbol.

val symbol_text_lazy : unit -> text Lazy.t

val rhs_text : int -> text

Fetch the text preceding the symbol at the given position.

val rhs_text_lazy : int -> text Lazy.t

---

🦋 Extra text

There may be additional text attached to the delimiters of a block (e.g. struct and end). This is fetched by the following functions, which are applied to the contents of the block rather than the delimiters. Sneaky, but iconic 💜

val symbol_pre_extra_text : unit -> text

Fetch additional text preceding the current symbol.

val symbol_post_extra_text : unit -> text

Fetch additional text following the current symbol.

val rhs_pre_extra_text : int -> text

Fetch additional text preceding the symbol at the given position.

val rhs_post_extra_text : int -> text

Fetch additional text following the symbol at the given position.

val rhs_post_text : int -> text

Fetch text following the symbol at the given position.

module WithMenhir : sig end

---

and that's the whole page bestie, you ate that 🍓✨ this lil doc drop is from OCamldoc, dated 2026-06-22, and it's Docstrings(3) all day every day — go forth and document responsibly, mwah 💋👑