Skip to content

Shape the Kotlin and Scala Server docs' "What is on here" as a capability directory - #127

Merged
tony merged 2 commits into
masterfrom
server-directory
Nov 1, 2026
Merged

tony merged 2 commits into
masterfrom
server-directory

Conversation

@tony

@tony tony commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Closes #126

Part of libtmux/docs#231

The Kotlin Server KDoc and the Scala Server Scaladoc now have the shape the docs site draws as a capability directory (groupDirectory), as the Java Server page already does: eight groups in each, a bold-led paragraph of guidance followed by a paragraph that holds only references. Until now each group mixed guidance and references in one paragraph, so libtmux.org rendered Kotlin and Scala as prose.

  • The introduction, the group titles and the guidance of every group are kept word for word, because the sentences tell members apart by name.
  • Each group's guidance is followed by one paragraph of the members it covers, as the KDoc [name] and [label][target] references and the Scaladoc [[name]] references the comments already used; types stay in the guidance only.
  • The closing paragraph about cmd, run, batch, chain and asJava (Kotlin) and cmd, run, batch and chain (Scala) is now its own group, "Running a command".
  • One commit per facade. Session already draws a directory on the Java side, and the Kotlin and Scala Session, Window and Pane comments have no grouped sections, so the issue's last bullet has nothing more to restructure.

The site does not read KDoc's [label][target] or Scaladoc's [[name]] references in the directory yet; libtmux/docs#231 adds them ([name] is already read). Until that lands the sections read as ordinary Markdown, which Dokka and Scaladoc render as before.

Checked:

  • ./gradlew :libtmux-scala:scaladocSite :libtmux-kotlin:dokkaGeneratePublicationHtml succeeds; the scaladoc task fails on an unresolved link and its two warnings are in Observation.scala, and Dokka links exactly the references it linked before the change
  • every reference of the old groups is still in the new ones, in both files
  • the docs-side parser work for Recognize every port's link syntax in the capability directory docs#231 draws eight rows for each new text and none for the old ones

tony added 2 commits November 1, 2026 08:52
why: Each group of the Kotlin `Server` KDoc's "What is on here" section
mixed guidance and `[name]` references in one paragraph, so libtmux.org
rendered it as prose, where the Java `Server` page draws a capability
directory. The site draws one only when a bold-led paragraph of guidance
is followed by a paragraph that holds nothing but references, in three
groups or more. libtmux/docs#231 teaches the parser KDoc's reference
syntax.

what:
- Keep the introduction, the group titles and the guidance of every
  group word for word, since its sentences tell members apart by name
- Follow each group's guidance with one paragraph of the members it
  covers, as the `[name]` and `[label][target]` references the comment
  already used; types stay in the guidance only
- Give the closing paragraph about `cmd`, `run`, `batch`, `chain` and
  `asJava` its own group, "Running a command"
why: Each group of the Scala `Server` Scaladoc's "What is on here"
section mixed guidance and `[[name]]` references in one paragraph, so
libtmux.org rendered it as prose, where the Java `Server` page draws a
capability directory. The site draws one only when a bold-led paragraph
of guidance is followed by a paragraph that holds nothing but
references, in three groups or more. libtmux/docs#231 teaches the parser
Scaladoc's reference syntax.

what:
- Keep the introduction, the group titles and the guidance of every
  group word for word, since its sentences tell members apart by name
- Follow each group's guidance with one paragraph of the members it
  covers, as the `[[name]]` references the comment already used; types
  stay in the guidance only
- Give the closing paragraph about `cmd`, `run`, `batch` and `chain` its
  own group, "Running a command"
@tony
tony marked this pull request as ready for review November 1, 2026 14:59
@tony
tony merged commit fc5df1f into master Nov 1, 2026
18 checks passed
tony added a commit that referenced this pull request Nov 1, 2026
why: Cut 0.1.2 from master so the test-run sandbox guard (#123) and its
cli await fix (#130), the per-module changelogs (#125) and the Kotlin and
Scala Server capability directory (#127) ship. The install snippets and
the examples' snapshot coordinates need to name the release that ships
them.

what:
- Date the 0.1.2 section (2026-11-01) in the root changelog and in each
  module's, and keep an empty unreleased section above it; the modules
  with nothing new say so
- Move the install snippets and the examples' snapshot coordinates to
  0.1.2
- Set the development version to 0.1.2-SNAPSHOT; libtmuxApiBaseline
  stays until 0.1.2 is published
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.

Write the Server capability directory in the shape the docs site draws

1 participant