Repository navigation
Clojure(docs): Write the capability directory - #165
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #163
The Clojure server page,
libtmux.core/open!, shows no "What is on here" table, where Julia'sLibTmux.Serverand Rust'sServerdo. This adds the directory to theopen!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 thelibtmux.corenamespace. The docs concept map binds the server concept tolibtmux.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 publiclibtmux.corevar is listed once, with thelibtmux.datavars a caller uses to traverse and filter a capture, andlibtmux.control/attach!.Reference spelling.
[[name]]for alibtmux.corevar 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 failscheck. libtmux/docs needs a Clojure entry inBY_PORTinapi-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.shslot wait):./gradlew :libtmux-clojure:checkcheckClojureApiReference./gradlew :libtmux-clojure:updateClojureApiReferencethencheckdocs/guide/clojure-api.mdregenerated and freshexportClojureApifrom libtmux/docs at this head, thenextractClojureandgroupDirectorywith the[[name]]pattern addedopen!body folds into 9 rows with 62 distinct references; without the pattern, 0 rowsThe new test,
server-directory-names-every-core-functioninlibtmux.internal.package-test, was shown to fail:libtmux.corevar reported missing.split-pane!dropped from the Create list, through./gradlew :libtmux-clojure:clojureTest:#{"libtmux.core/split-pane!"}reported missing.thenamong the references of the Remove list: the prose assertion failed. (andis 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!]]"] } ] }