Skip to content

Correct the count of operations gRPC cannot serve, and the punctuation around them - #70

Merged
tonytonycoder11 merged 2 commits into
mainfrom
docs/punctuation-and-emphasis
Jul 31, 2026
Merged

Correct the count of operations gRPC cannot serve, and the punctuation around them#70
tonytonycoder11 merged 2 commits into
mainfrom
docs/punctuation-and-emphasis

Conversation

@tonytonycoder11

@tonytonycoder11 tonytonycoder11 commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Two passes over the prose. No behaviour change, one KDoc touched.

The count was wrong

GrpcQdrantTransport's KDoc said eleven operations have no gRPC equivalent. There are fourteen. The
number was written from memory and never checked, and from that KDoc it reached the README,
STABILITY.md, the migration guide and the changelog.

grep -o 'restOnly("[a-zA-Z]*")' GrpcQdrantTransport.kt | sort -u | wc -l
14

Two things made it wrong. The enumeration said "the five shard-scope snapshot operations" and there are
six, because recoverShardSnapshot was missing. And downloadStorageSnapshot was left out of the list
altogether.

The enumeration now follows how the code groups them, so the next reader can arrive at fourteen without
reconstructing the list: the two issues calls, the snapshot and storage-snapshot transfers, and the six
shard-scope operations.

Punctuation and emphasis

Twenty-two em dashes across the same files, several of them standing in for two different marks inside
one sentence. Each is replaced by what the sentence wanted: a colon where a list follows, a full stop
between two independent clauses, commas around a genuine aside.

File em dashes boldface
README.md 8 → 1 8 → 7
STABILITY.md 8 → 0 19 → 9
docs/migrating-from-qdrant-client.md 5 → 0 0
CONTRIBUTING.md 1 → 0 0
CHANGELOG.md, [2.0.0] only 4 → 0 8 → 7

The one left in the README is the status blockquote, whose shape STANDARD.md prescribes and
audit-library.sh greps for.

STABILITY.md had nine paragraphs opening with a bolded sentence doing the work of a heading. When
every paragraph carries an emphasised line, none of them is emphasised. What survives marks MAJOR,
MINOR and PATCH, where the bold separates a defined term from its definition.

Changelog sections before 2.0.0 are left alone: their text generated the GitHub Release bodies at the
time, and rewriting them would leave the two disagreeing about a release nobody can cut again.

./gradlew build green, audit At standard. The v2.0.0 Release body needs regenerating from the
corrected changelog after merge.

Twenty-two em dashes across the README, STABILITY.md, the migration guide,
CONTRIBUTING.md and the 2.0.0 changelog section, replaced with whatever the
sentence actually wanted: a colon before a list, a full stop between two
independent clauses, commas around a real aside. Several of them were
standing in for two different marks in the same sentence, which is where
the habit stops being shorthand and starts costing the reader.

The one that stays is the status blockquote, whose shape STANDARD.md
prescribes and the audit script checks.

Mechanical boldface goes with it. STABILITY.md had nine paragraphs opening
with a bolded sentence acting as a heading, and when every paragraph
carries an emphasised line none of them is emphasised. Nineteen down to
nine; what remains marks MAJOR, MINOR and PATCH, where the bold separates
a defined term from its definition.

Changelog sections older than 2.0.0 keep their punctuation. Their text
generated the GitHub Release bodies at the time, and editing them now
would leave the two disagreeing about a release nobody can cut again.
@tonytonycoder11
tonytonycoder11 requested a review from a team as a code owner July 31, 2026 15:36
Fourteen, not eleven. The number came from the KDoc on GrpcQdrantTransport,
where it was written from memory and never checked against the class, and
from there it reached the README, STABILITY.md, the migration guide and the
changelog.

Two mistakes made it wrong. The enumeration said "the five shard-scope
snapshot operations" and there are six, since recoverShardSnapshot was
missing from the list. And downloadStorageSnapshot was left out entirely.

Counting the call sites settles it:

  grep -o 'restOnly("[a-zA-Z]*")' GrpcQdrantTransport.kt | sort -u | wc -l
  14

The enumeration is now written the way the code groups them, so the next
person can count the same fourteen without reconstructing the list: the two
issues calls together, the snapshot and storage-snapshot transfers together,
and the six shard-scope operations as a group.
@tonytonycoder11 tonytonycoder11 changed the title Punctuate the documentation the way the sentences read Correct the count of operations gRPC cannot serve, and the punctuation around them Jul 31, 2026
@tonytonycoder11
tonytonycoder11 merged commit deb3c06 into main Jul 31, 2026
7 checks passed
@tonytonycoder11
tonytonycoder11 deleted the docs/punctuation-and-emphasis branch July 31, 2026 15:46
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.

1 participant