Documenting your modules
Osprey builds API documentation directly from your modules and the compiler's inferred types. Both Default and ML sources support documentation comments.
Write comments and examples
In Default source, put /// above a declaration. Use //! at the beginning of
a file, namespace, or module to document that scope.
//! Greetings for command-line applications.
/// Greets a reader by name.
///
/// # Parameters
/// - name: the reader's display name
/// # Returns
/// The greeting text.
/// # Examples
/// ```osprey
/// print(greet("Osprey"))
/// ```
/// ```output
/// Hello Osprey!
/// ```
fn greet(name) = "Hello " + name + "!"
//! Greetings for command-line applications.
(** Greets a reader by name.
# Parameters
- name: the reader's display name
# Returns
The greeting text.
# Examples
```osprey
print (greet "Osprey")
```
```output
Hello Osprey!
```
*)
greet name = "Hello " + name + "!"
ML uses (** ... *) above declarations and the same //! inner comments.
Example code is interpreted in the source file's flavor. The structured sections
also support # Raises, # See also, # Since, and # Deprecated, plus aliases
such as @param, @return, and @author. Use [Name] to refer to another API.
Generate a site
osprey --docs ./my-project --docs-dir ./site --docs-format html
Open site/index.html or serve it statically. Browse modules, public members, inferred signatures, examples, search and built-ins. Single .osp/.ospml files and libraries without entry points also work.
Function pages show which effect operations their callers must provide, including requests made through helpers. They also list runtime operations and explicitly flag callbacks whose effects remain unresolved. These are the same details shown in editor hover, signature help and completion. Written effect annotations remain visible as bounds; they are separate from the operations the compiler finds.
The State boundaries page (api/project/state-boundaries.html) lists state owners, private-cell counts and exported effects, including private-module owners. It hides cell names, initial values and private helpers. Editor/CLI state warnings show the same ownership information. Handler installation creates fresh cells; imports do not share an instance.
Choose a built-in theme:
| Theme | Appearance |
|---|---|
osprey |
Blue reference layout with module cards and an article outline |
midnight |
Dark console layout with compact spacing and monospaced details |
paper |
Editorial layout with serif headings and ruled lists |
osprey --docs ./my-project --docs-dir ./site --docs-format html --docs-theme midnight
Expand navigation groups to browse your modules and guides, or press / to
search. Code examples retain their exact text when copied.
Omit the source to export the built-in reference alone. Omit --docs-format html
to generate Markdown with front matter for use in an existing documentation site.
Add guides and branding
osprey --docs ./my-project --docs-dir ./site --docs-format html \
--docs-page ./guides --docs-page ./release-notes.md --docs-css ./brand.css
Markdown pages join the site's navigation and search. Directories are scanned recursively. Tables, fenced code, footnotes, task lists and ordinary Markdown links are supported. Raw HTML is shown as text.
Custom styles load after the theme. For example, brand.css can change the
accent while retaining the responsive layout:
:root {
--accent: #7145b8;
--accent-soft: #f0e9fa;
}
.article { max-width: 76ch; }
Pass multiple --docs-css options to layer styles in order. The generated
assets/theme.css is also a complete starting point for a custom design.
Test the examples
osprey ./my-project --doctests
osprey ./my-project --doctests --memory=arc
osprey ./my-project --doctests --target=wasm32 --memory=arc
Every example is type-checked. An immediately following output fence makes
it executable and asserts its stdout exactly, including spaces. An example
without an output fence is checked without running. Each example has its own
bindings and can use the documented declaration's module scope. Application
entry code is not run automatically; examples may call main explicitly.
A failed example produces a diagnostic and a failing exit status. Runnable
examples have a 30-second execution limit; set OSPREY_DOCTEST_TIMEOUT_MS to
another positive duration in milliseconds when needed. The WASM mode uses
wasmtime, or the executable selected by OSPREY_WASM_RUN.