Skip to content

Clojure(docs): Write the capability directory - #165

Merged
tony merged 2 commits into
masterfrom
docs/clojure-server-directory
Nov 14, 2026
Merged

tony merged 2 commits into
masterfrom
docs/clojure-server-directory

Conversation

@tony

@tony tony commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Closes #163

The Clojure server page, libtmux.core/open!, shows no "What is on here" table, where Julia's LibTmux.Server and Rust's Server do. This adds the directory to the open! docstring. The table appears on that page once this merges and libtmux/docs reads the [[name]] spelling (libtmux/docs#318).

Owner symbol. libtmux.core/open!, not the libtmux.core namespace. The docs concept map binds the server concept to libtmux.core/open!, so that is the page other ports link as Clojure's server and the page the issue reports. The namespace docstring is two sentences on the module page, which already lists its vars.

What is on it. Nine rows, each a bold lead, guidance, and a Label: [[ref]], [[ref]] list: connecting and closing, listing everything, finding one thing, creating and removing, acting on objects, typing into panes and reading them, options and hooks and environment, buffers and channels, running a command. Every public libtmux.core var is listed once, with the libtmux.data vars a caller uses to traverse and filter a capture, and libtmux.control/attach!.

Reference spelling. [[name]] for a libtmux.core var and [[libtmux.data/name]] for another namespace, the cljdoc wiki link WRITING.md prescribes and the native reference already resolves. It rejects an unknown target, so a renamed var fails check. libtmux/docs needs a Clojure entry in BY_PORT in api-directory.ts, /\[\[[^\]\n]+\]\]/; until then the shell reads Clojure with the shared patterns and draws no table.

Changelog. None: the Clojure module has not shipped, and the unreleased Documented entry already covers its API references.

Verification

Run on this branch (wall time includes the heavy.sh slot wait):

Command Result
./gradlew :libtmux-clojure:check pass, 39 s: 61 tests, 371 assertions, plus checkClojureApiReference
./gradlew :libtmux-clojure:updateClojureApiReference then check docs/guide/clojure-api.md regenerated and fresh
exportClojureApi from libtmux/docs at this head, then extractClojure and groupDirectory with the [[name]] pattern added 90 declarations exported; the open! body folds into 9 rows with 62 distinct references; without the pattern, 0 rows

The new test, server-directory-names-every-core-function in libtmux.internal.package-test, was shown to fail:

  • On the base docstring (no directory): 0 rows, and every public libtmux.core var reported missing.
  • With split-pane! dropped from the Create list, through ./gradlew :libtmux-clojure:clojureTest: #{"libtmux.core/split-pane!"} reported missing.
  • With the word then among the references of the Remove list: the prose assertion failed. (and is allowed, as the site allows it.)

First row as exported by the docs model:

{
  "title": "Connecting and closing",
  "guidance": "[[open!]] returns a Server for one explicit `:socket-path` or `:socket-name`, which `with-open` closes. [[close!]] releases only that client and never kills tmux. [[libtmux.control/attach!]] attaches a separate control connection to a captured session.",
  "groups": [
    { "label": "Open and close", "refs": ["[[open!]]", "[[close!]]"] },
    { "label": "Control", "refs": ["[[libtmux.control/attach!]]"] }
  ]
}

tony added 2 commits November 14, 2026 13:12
why: libtmux.org shows Clojure's server on the `open!` page, and that
page had no "What is on here" table, which the server pages of other
ports draw. The site folds a bold-led paragraph followed by a list of
`Label: reference, reference` items into a row, and draws a table from
three rows.

what:
- Add a "What is on here" section to the `open!` docstring with nine
  rows: connecting, listing, finding one thing, creating and removing,
  acting on objects, typing into and reading panes, options and hooks
  and environment, buffers and channels, and running a command
- List every public `libtmux.core` var once, with the `libtmux.data` and
  `libtmux.control` vars a caller uses to traverse, filter and attach
- Write references as `[[name]]` and `[[namespace/name]]`, as the other
  docstrings do, so the native reference rejects a name that goes stale
- Regenerate docs/guide/clojure-api.md, which `check` compares with the
  public var metadata
why: Nothing failed when a public `libtmux.core` var was added without a
row in the `open!` directory, or when a row stopped being a bold lead
followed by a list of references, the shape libtmux.org needs to draw
its table. Both would leave the page without the var, or without the
table, until a reader noticed.

what:
- Parse the "What is on here" section of the `open!` docstring into rows
  and assert at least three, each a bold lead followed by `Label:` items
  holding only `[[reference]]` entries
- Assert every public, documented `libtmux.core` var appears in a list
@tony
tony merged commit 9cbaef3 into master Nov 14, 2026
29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clojure reference has no capability directory on its server page

1 participant