docs: various tiny doc fixes #450

m4tx · 2026-01-19T11:32:41Z

No description provided.

Copilot

Pull request overview

This PR contains various documentation improvements across the Cot web framework codebase. The changes focus on improving clarity, consistency, and grammatical correctness of documentation comments, error messages, and CLI descriptions throughout the project.

Changes:

Improved documentation phrasing for better readability and consistency (e.g., "Sends a GET request" instead of "Send a GET request")
Corrected grammatical issues and standardized terminology (e.g., "test configuration" instead of "test config", "specifications" instead of "specs")
Enhanced error message descriptions to be more descriptive and clear
Updated CLI tool description to be more professional and concise
Fixed minor typos and spelling errors in code comments and examples

Reviewed changes

Copilot reviewed 39 out of 41 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cot/src/test.rs	Improved documentation clarity for test client and methods
cot/src/static_files.rs	Enhanced module and macro documentation
cot/src/session.rs	Refined module documentation phrasing
cot/src/router.rs	Improved documentation for router methods and parameter descriptions
cot/src/response.rs	Fixed grammar and improved trait documentation
cot/src/request.rs	Enhanced method documentation clarity
cot/src/project.rs	Improved trait and method documentation, fixed comment formatting
cot/src/openapi.rs	Enhanced OpenAPI-related documentation
cot/src/middleware.rs	Fixed grammar and spelling in middleware documentation
cot/src/json.rs	Corrected terminology ("RESTful" instead of "REST-ful")
cot/src/html.rs	Improved safety documentation phrasing
cot/src/handler.rs	Simplified error documentation
cot/src/form.rs	Enhanced error message and method documentation
cot/src/db/migrations.rs	Improved migration engine documentation
cot/src/db.rs	Enhanced error documentation and method descriptions
cot/src/config.rs	Fixed grammar and improved configuration documentation
cot/src/common_types.rs	Corrected article usage and improved method documentation
cot/src/cli.rs	Enhanced CLI registration documentation
cot/src/cache/store/redis.rs	Improved Redis store documentation
cot/src/cache/store/memory.rs	Enhanced in-memory store documentation
cot/src/cache/store.rs	Fixed grammar in trait documentation
cot/src/cache.rs	Removed redundant documentation and fixed comment formatting
cot/src/body.rs	Consolidated error documentation
cot/src/auth/db.rs	Improved database authentication documentation
cot/src/auth.rs	Fixed typos and enhanced authentication trait documentation
cot/src/admin.rs	Updated admin trait documentation and fixed import examples
cot-macros/src/lib.rs	Improved macro documentation clarity
cot-codegen/src/symbol_resolver.rs	Fixed extra space in documentation
cot-cli/src/migration_generator.rs	Enhanced migration generation error messages and documentation
cot-cli/src/args.rs	Standardized CLI argument documentation format
cot-cli/Cargo.toml	Updated package description to be more professional
Snapshot test files	Updated to reflect new CLI description

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cot/src/admin.rs

github-actions · 2026-01-19T11:36:57Z

Bencher Report

Branch	doc-fixes
Testbed	github-ubuntu-latest

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold	4,519.80 µs (-24.57%) Baseline: 5,991.69 µs	7,069.95 µs (63.93%)
json_api/json_api	📈 view plot 🚷 view threshold	869.85 µs (-14.58%) Baseline: 1,018.32 µs	1,153.63 µs (75.40%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	806.09 µs (-14.23%) Baseline: 939.84 µs	1,059.16 µs (76.11%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	769.90 µs (-14.46%) Baseline: 900.04 µs	1,014.86 µs (75.86%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	16,342.00 µs (-7.07%) Baseline: 17,584.80 µs	20,973.77 µs (77.92%)

🐰 View full continuous benchmarking report in Bencher

cot-cli/src/migration_generator.rs

seqre · 2026-01-19T11:42:42Z

cot-cli/src/args.rs

Looking at the snapshots, () are still used for defaults, so I think we should keep using them for standardization sake.

Looks like I forgot to regenerate the snapshots. Have a look now - I've unified them so that they all use square brackets now.

cot/src/auth.rs

ElijahAhianyo · 2026-01-19T13:01:35Z

cot-macros/src/lib.rs

-///   because the model might have changed since the migration was generated.
-///   You can, however, use the migration model, which will always represent
-///   the state of the model at the time the migration runs.
+///   engine knows what the state of model was at the time the last migration


I feel like the whole Paragraph could be worded like so:

/// Migration models have two major uses. First, they ensure that the migration engine /// knows what state the model was in at the time the last migration was generated. /// This allows the engine to automatically detect the changes and generate the necessary migration code. /// Second, they allow custom code in migrations: you might want the migration to fill in some data, for example. /// You cannot use the actual model for this because the /// model might have changed since the migration was generated. /// You can, however, use the migration model, which will always represent the state of the model at the time the migration runs.

Sounds better, thanks!

ElijahAhianyo · 2026-01-19T13:04:41Z

cot-macros/src/lib.rs

+///   custom code in the migrations: you might want the migration to fill in
+///   some data, for example. You can't use the actual model for this because
+///   the model might have changed since the migration was generated. You can,
+///   however, use the migration model, which will always represent the state of
+///   the model at the time the migration runs.


This part is not so clear. Perhaps an actual code example to illustrate what you can't do with the actual model, but can with the migration model, should help clear things up?

I've rephrased this a little bit, hopefully it's a bit clearer now. Sadly it's difficult to convey the meaning in short docs - I think this deserves a chapter in the guide on ORM instead. And also the docs "custom code" here, which is a feature that hasn't landed yet. I'll try to work on both very soon.

The custom migration feature is being iterated in this PR: #455

cot-macros/src/lib.rs

cot/src/auth.rs

cot/src/project.rs

cot/src/request.rs

ElijahAhianyo · 2026-01-19T14:06:47Z

cot/src/request.rs

-    /// Get the route name, or [`None`] if the request is not routed or doesn't
-    /// have a route name.
+    /// Returns the name of the current route, or [`None`] if the request is not
+    /// routed or doesn't have a route name.


Suggested change

/// routed or doesn't have a route name.

/// routed or does not have a route name.

"Does not" sounds a lot formal imo.
Alternatively(and debatable), perhaps the sentence could use bullet points for clarity:

/// Returns the name of the current route, or [`None`] if: /// /// - the request was not routed. /// - the route has no name. ///

I've changed it slightly, so that the None part is in a separate paragraph. I generally try to stick to "the gist goes into the first paragraph" rule, so that you can immediately see what the function/structure/module is doing in general, and then you can dive into details. In case of structures and modules, the first paragraph is also what rustdoc displays on the list view, so it's even more important there.

cot/src/router.rs

Co-authored-by: EBADF <elijahahianyo@gmail.com>

Co-authored-by: Marek Grzelak <git@seqre.dev>

codecov · 2026-01-26T20:09:43Z

Codecov Report

❌ Patch coverage is 0% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot-cli/src/migration_generator.rs	0.00%	5 Missing and 1 partial ⚠️

Flag	Coverage Δ
rust	`90.35% <0.00%> (-0.02%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cot-codegen/src/symbol_resolver.rs	`97.66% <ø> (ø)`
cot-core/src/body.rs	`84.89% <ø> (ø)`
cot-core/src/handler.rs	`78.26% <ø> (ø)`
cot-core/src/html.rs	`97.44% <ø> (ø)`
cot-core/src/response.rs	`97.50% <ø> (ø)`
cot-macros/src/lib.rs	`94.50% <ø> (ø)`
cot/src/admin.rs	`72.06% <ø> (ø)`
cot/src/auth.rs	`93.14% <ø> (ø)`
cot/src/auth/db.rs	`85.21% <ø> (ø)`
cot/src/cache.rs	`84.37% <ø> (ø)`
... and 18 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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

docs: various tiny doc fixes

839bad4

m4tx requested review from ElijahAhianyo, Copilot and seqre January 19, 2026 11:32

github-actions bot added C-cli Crate: cot-cli (issues and Pull Requests related to Cot CLI) C-lib Crate: cot (main library crate) C-macros Crate: cot-macros C-codegen Crate: cot-codegen labels Jan 19, 2026

Copilot started reviewing on behalf of m4tx January 19, 2026 11:33 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

cot/src/admin.rs Show resolved Hide resolved

cot/src/admin.rs Show resolved Hide resolved

cot/src/admin.rs Show resolved Hide resolved

seqre reviewed Jan 19, 2026

View reviewed changes

ElijahAhianyo requested changes Jan 19, 2026

View reviewed changes

m4tx and others added 4 commits January 26, 2026 18:42

Update cot/src/router.rs

f0938f1

Co-authored-by: EBADF <elijahahianyo@gmail.com>

Apply suggestions from code review

959c74b

Co-authored-by: EBADF <elijahahianyo@gmail.com>

Update cot/src/auth.rs

fef7e77

Co-authored-by: Marek Grzelak <git@seqre.dev>

random fixes

c88f530

m4tx added 3 commits January 27, 2026 00:21

Merge branch 'master' into doc-fixes

eb65aef

fixes

b3c04ad

restful

849cdac

m4tx requested review from ElijahAhianyo and seqre January 26, 2026 23:41

Merge branch 'master' into doc-fixes

bd9ea48

seqre approved these changes Jan 27, 2026

View reviewed changes

m4tx merged commit b8037bf into master Jan 27, 2026
39 of 40 checks passed

m4tx deleted the doc-fixes branch January 27, 2026 19:29

cotbot bot mentioned this pull request Jan 27, 2026

chore: release #456

Open

	/// routed or doesn't have a route name.
	/// routed or does not have a route name.

Uh oh!

docs: various tiny doc fixes #450

docs: various tiny doc fixes #450

Uh oh!

Conversation

m4tx commented Jan 19, 2026

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!

github-actions bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ElijahAhianyo Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Jan 19, 2026 •

edited

Loading

ElijahAhianyo Jan 19, 2026 •

edited

Loading

codecov bot commented Jan 26, 2026 •

edited

Loading