Fix grammar in doc comments: restrictive "which" → "that", possessives, and related issues by alexander-yevsyukov · Pull Request #946 · SpineEventEngine/base-libraries

alexander-yevsyukov · 2026-06-15T19:27:45Z

This branch carries several independent improvements; the doc grammar sweep is the main new work.

Doc-comment grammar fixes (new in this branch)

Replace ~100 occurrences of restrictive which (no comma) with that in KDoc/Javadoc across annotations/, base/, buildSrc/, environment/, and format/.
Fix possessive constructions: column which actual value → column whose actual value is used, entities which column value → entities whose column value, file which name → file whose name, annotation which simple name → annotation whose simple name.
Fix ComparableStringValue: remove erroneous comma before which, change to that.
Fix two stub-class comments in ThrowableExtsTest: which → that.
Fix typo: "for mor details" → "for more details" in EntityStateSpec.
Fix tense: entity that thrown → entity that threw in RejectionThrowable.
Fix subject-verb agreement: expressions that results → expressions that result in CartesianProducts.

Left untouched: prepositional phrases (in which, of which, etc.), interrogative determiners (Defines which fields, Controls which class), and non-restrictive , which clauses that already had a comma.

Other notable changes

@Serial annotations: added to serialVersionUID fields in several classes.

Further steps

Create which-fixer skill under agents.
Apply the buildSrc language fixes to config.

🤖 Generated with Claude Code
🙌🏻 Updated by @alexander-yevsyukov

codecov · 2026-06-15T19:32:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.04%. Comparing base (0350edb) to head (1532a23).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #946   +/-   ##
=======================================
  Coverage   94.04%   94.04%           
=======================================
  Files         192      192           
  Lines        4149     4149           
  Branches      339      339           
=======================================
  Hits         3902     3902           
  Misses        147      147           
  Partials      100      100

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR primarily standardizes doc-comment grammar across the repository by replacing restrictive which with that and fixing a few possessive cases (which → whose), alongside broad license-header normalization (copyright year and http→https).

Changes:

Performed a large-scale KDoc/Javadoc grammar sweep (which→that, plus a few which→whose) across annotations/, base/, environment/, and format/.
Normalized many file headers (copyright year to 2026 and Apache License URL to https).
Included a version bump in version.gradle.kts and added @Serial annotations to several serialVersionUID declarations (not doc-only).

Reviewed changes

Copilot reviewed 110 out of 110 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
version.gradle.kts	Bumps `versionToPublish` snapshot version.
format/src/test/kotlin/io/spine/format/FormatTest.kt	KDoc grammar updates in test base class documentation.
format/src/main/kotlin/io/spine/format/parse/Parser.kt	KDoc grammar and header normalization.
environment/src/main/java/io/spine/environment/TestsProperty.java	Javadoc grammar tweaks and header URL/year normalization.
environment/src/main/java/io/spine/environment/Environment.java	Javadoc grammar tweaks and header URL/year normalization.
buildSrc/src/main/kotlin/Strings.kt	KDoc grammar tweaks and header normalization.
buildSrc/src/main/kotlin/LicenseSettings.kt	Header formatting normalization + KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/testing/TestKitCoverage.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/RunGradle.kt	KDoc grammar tweaks and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/report/license/Paths.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/report/license/ModuleDataExtensions.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/report/license/LicenseReporter.kt	KDoc grammar tweaks.
buildSrc/src/main/kotlin/io/spine/gradle/repo/Repository.kt	KDoc grammar tweaks, header normalization, whitespace cleanup.
buildSrc/src/main/kotlin/io/spine/gradle/publish/SpinePublishing.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/publish/PublishingExts.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/publish/PublicationHandler.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/publish/JarDsl.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/publish/IncrementGuard.kt	KDoc grammar tweaks.
buildSrc/src/main/kotlin/io/spine/gradle/publish/GitHubPackages.kt	KDoc grammar tweaks and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/publish/CustomPublicationHandler.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/publish/CheckVersionIncrement.kt	Header normalization + KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/javascript/task/Assemble.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/javascript/JsExtension.kt	KDoc grammar tweaks and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/javascript/JsEnvironment.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/javadoc/ExcludeInternalDoclet.kt	KDoc grammar tweaks.
buildSrc/src/main/kotlin/io/spine/gradle/java/Tasks.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/github/pages/UpdateGitHubPages.kt	KDoc grammar tweaks.
buildSrc/src/main/kotlin/io/spine/gradle/github/pages/TaskName.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/dart/task/IntegrationTest.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/gradle/dart/DartExtension.kt	KDoc grammar tweaks and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/dart/DartEnvironment.kt	KDoc grammar tweaks and header normalization.
buildSrc/src/main/kotlin/io/spine/gradle/ConfigTester.kt	KDoc grammar tweaks.
buildSrc/src/main/kotlin/io/spine/dependency/lib/Kotlin.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/dependency/lib/CommonsCli.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/io/spine/dependency/Dependency.kt	KDoc grammar tweaks and whitespace cleanup.
buildSrc/src/main/kotlin/io/spine/dependency/boms/BomsPlugin.kt	KDoc grammar tweak and header normalization.
buildSrc/src/main/kotlin/DokkaExts.kt	KDoc grammar tweak.
buildSrc/src/main/kotlin/BuildExtensions.kt	Punctuation tweak for non-restrictive clause.
base/src/test/kotlin/io/spine/type/MessageClassSpec.kt	Adds `@Serial` to `serialVersionUID` and normalizes headers/docs.
base/src/test/kotlin/io/spine/base/ThrowableExtsTest.kt	KDoc grammar tweaks + adds `@Serial` to stub `serialVersionUID` fields.
base/src/test/kotlin/io/spine/base/MistakeSpec.kt	Adds `@Serial` to `serialVersionUID`.
base/src/test/kotlin/io/spine/base/EntityStateSpec.kt	Fixes typo (“mor”→“more”) + adds `@Serial` constants.
base/src/test/java/io/spine/type/TypeNameTest.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/test/java/io/spine/query/RecordQueryTest.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/kotlin/io/spine/string/Stringify.kt	KDoc grammar tweaks and header URL/year normalization.
base/src/main/kotlin/io/spine/string/Separator.kt	KDoc grammar tweak and header normalization.
base/src/main/kotlin/io/spine/security/CallerProvider.kt	KDoc grammar tweaks and header normalization.
base/src/main/kotlin/io/spine/protobuf/ProtoConverter.kt	KDoc grammar tweak and header normalization.
base/src/main/kotlin/io/spine/io/Glob.kt	KDoc grammar tweaks and header normalization.
base/src/main/kotlin/io/spine/collect/IterableExts.kt	KDoc grammar tweak and header normalization.
base/src/main/kotlin/io/spine/code/proto/FileDescriptorSetReader.kt	KDoc grammar tweak, header normalization, and spacing.
base/src/main/kotlin/io/spine/code/proto/DescriptorSetReferenceFile.kt	KDoc grammar tweak and header normalization.
base/src/main/kotlin/io/spine/base/Mistake.kt	Adds `@Serial` to `serialVersionUID` and header normalization.
base/src/main/kotlin/io/spine/base/EntityState.kt	KDoc grammar tweak.
base/src/main/java/io/spine/value/ComparableStringValue.java	Javadoc grammar tweak + adds `@Serial` to `serialVersionUID`.
base/src/main/java/io/spine/util/Predicates2.java	Javadoc grammar tweak.
base/src/main/java/io/spine/util/Preconditions2.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/type/UnpublishedLanguageException.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/type/Type.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/type/SerializableMessage.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/type/KnownMessage.java	Javadoc grammar tweak and header normalization.
base/src/main/java/io/spine/type/ApiOption.java	Javadoc grammar tweaks + whitespace cleanup in method body.
base/src/main/java/io/spine/string/Diags.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/SubjectParameter.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/SortBy.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/RecordQueryBuilder.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/RecordQuery.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/RecordPredicates.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/RecordCriterion.java	Possessive fix (`which`→`whose`) + header URL/year normalization.
base/src/main/java/io/spine/query/RecordColumns.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/QueryPredicate.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/QueryCriterion.java	Javadoc grammar tweak (needs follow-up correction).
base/src/main/java/io/spine/query/QueryBuilder.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/package-info.java	Package-level Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/OrExpression.java	Possessive fix (`which`→`whose`) + header URL/year normalization.
base/src/main/java/io/spine/query/IdParameter.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/IdCriterion.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/EntitySubjectParameter.java	Possessive fix (`which`→`whose`) + header URL/year normalization.
base/src/main/java/io/spine/query/EntityQueryBuilder.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/EntityCriterion.java	Possessive fix (`which`→`whose`) + header URL/year normalization.
base/src/main/java/io/spine/query/EntityColumn.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/CustomSubjectParameter.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/CustomCriterion.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/CustomColumn.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/query/Columns.java	Javadoc grammar tweaks.
base/src/main/java/io/spine/query/CartesianProducts.java	Javadoc grammar tweak (needs follow-up correction) and header URL/year normalization.
base/src/main/java/io/spine/query/AndExpression.java	Javadoc grammar tweak (needs follow-up correction) and header URL/year normalization.
base/src/main/java/io/spine/query/AbstractQueryBuilder.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/query/AbstractQuery.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/protobuf/AnyPacker.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/proto/TypeSet.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/proto/SourceFile.java	Javadoc grammar tweak.
base/src/main/java/io/spine/code/proto/Option.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/proto/FileSet.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/proto/FileDescriptors.java	Javadoc grammar tweaks, header URL/year normalization, and spacing.
base/src/main/java/io/spine/code/proto/FieldTypes.java	Javadoc grammar tweaks.
base/src/main/java/io/spine/code/proto/FieldDeclaration.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/proto/EntityStateOption.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/proto/ColumnOption.java	Javadoc grammar tweak and header URL/year normalization.
base/src/main/java/io/spine/code/java/ClassName.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/code/fs/AbstractFileName.java	Adds `@Serial` to `serialVersionUID`.
base/src/main/java/io/spine/base/SubscribableField.java	Javadoc grammar tweaks and header URL/year normalization.
base/src/main/java/io/spine/base/Routable.java	Javadoc grammar tweak and header normalization.
base/src/main/java/io/spine/base/RejectionThrowable.java	Javadoc grammar tweak (needs follow-up correction) + spacing.
base/src/main/java/io/spine/base/MessageFile.java	Possessive fix (`which`→`whose`) + header URL/year normalization.
base/src/main/java/io/spine/base/Field.java	Javadoc grammar tweaks and header URL/year normalization.
annotations/src/test/java/io/spine/annotation/GeneratedJavaSpec.java	Javadoc grammar tweak and header normalization.
annotations/src/main/kotlin/io/spine/annotation/Modified.kt	KDoc grammar tweaks and header normalization.
annotations/src/main/kotlin/io/spine/annotation/GeneratedMixin.kt	KDoc grammar tweaks and header normalization.
annotations/src/main/kotlin/io/spine/annotation/Generated.kt	KDoc grammar tweak and header normalization.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 110 out of 110 changed files in this pull request and generated 8 comments.

…iterion` "whose actual value to use later" → "whose actual value is used later" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 112 out of 112 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 117 out of 117 changed files in this pull request and generated 1 comment.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 117 out of 117 changed files in this pull request and generated 2 comments.

 * Thrown when a Protobuf type having the {@code internal_type} option is sent
- * to a bounded context which declares it. Or, when the declaring bounded context attempts
+ * to a bounded context that declares it. Or, when the declaring bounded context attempts
 * to send this type outside.


 /**
- * A utility class which allows to obtain Protobuf file descriptors.
+ * A utility class that allows to obtain Protobuf file descriptors.
 */


alexander-yevsyukov added 4 commits June 15, 2026 19:25

Bump version -> 2.0.0-SNAPSHOT.412

9b211a7

Apply @Serial annotation

c76fcea

Fix typo

cbc7b42

Fix "that/which" language in the docs

2fa9e08

Copilot AI review requested due to automatic review settings June 15, 2026 19:27

Copilot started reviewing on behalf of alexander-yevsyukov June 15, 2026 19:28 View session

Copilot AI reviewed Jun 15, 2026

View reviewed changes

alexander-yevsyukov self-assigned this Jun 15, 2026

alexander-yevsyukov added this to v2.0 Jun 15, 2026

alexander-yevsyukov moved this to 🏗 In progress in v2.0 Jun 15, 2026

Improve doc language

087344b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 15, 2026 19:37

Copilot started reviewing on behalf of alexander-yevsyukov June 15, 2026 19:38 View session

alexander-yevsyukov and others added 6 commits June 15, 2026 22:38

FIx doc language

9ceceb2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix doc language

757065c

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix plurals in docs

05ffd01

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix doc language

f4bed31

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix doc language

e7aa475

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix doc language

5e9e045

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jun 15, 2026

View reviewed changes

alexander-yevsyukov and others added 2 commits June 15, 2026 20:42

Update dependency reports

548997e

Fix incomplete verb in @param doc for RecordCriterion and `EntityCr…

5f2b278

…iterion` "whose actual value to use later" → "whose actual value is used later" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings June 15, 2026 19:45

alexander-yevsyukov added 2 commits June 15, 2026 20:46

Bump local dependencies

7e25a05

Bump local dependencies

5e5803b

alexander-yevsyukov changed the title ~~Fix grammar: use "that" for restrictive clauses and "whose" for possessives in doc comments~~ Fix grammar in doc comments: restrictive "which" → "that", possessives, and related issues Jun 15, 2026

Fix logging message

6628f75

Copilot started reviewing on behalf of alexander-yevsyukov June 15, 2026 19:46 View session

Copilot AI reviewed Jun 15, 2026

View reviewed changes

alexander-yevsyukov requested a review from Copilot June 15, 2026 19:53

Copilot started reviewing on behalf of alexander-yevsyukov June 15, 2026 19:53 View session

alexander-yevsyukov requested a review from armiol June 15, 2026 19:54

alexander-yevsyukov enabled auto-merge June 15, 2026 19:56

Copilot AI reviewed Jun 15, 2026

View reviewed changes

Comment thread environment/src/main/java/io/spine/environment/TestsProperty.java Outdated

alexander-yevsyukov disabled auto-merge June 15, 2026 20:00

Improve doc language

1532a23

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 15, 2026 20:00

Copilot started reviewing on behalf of alexander-yevsyukov June 15, 2026 20:01 View session

Copilot AI reviewed Jun 15, 2026

View reviewed changes

armiol approved these changes Jun 16, 2026

View reviewed changes

Conversation

alexander-yevsyukov commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Doc-comment grammar fixes (new in this branch)

Other notable changes

Further steps

Uh oh!

codecov Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexander-yevsyukov commented Jun 15, 2026 •

edited

Loading

codecov Bot commented Jun 15, 2026 •

edited

Loading