docs: various tiny doc fixes

clippy.toml

@@ -1,2 +1,2 @@
 avoid-breaking-exported-api = false
-doc-valid-idents = ["PostgreSQL", "MySQL", "SQLite", "OpenAPI", ".."]
+doc-valid-idents = ["PostgreSQL", "MySQL", "SQLite", "OpenAPI", "RESTful", ".."]

cot-cli/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "cot-cli"
 version = "0.5.0"
-description = "The Rust web framework for lazy developers - CLI tool."
+description = "Command-line interface for the Cot web framework"
 categories = ["command-line-utilities", "web-programming"]
 edition.workspace = true
 rust-version.workspace = true

cot-cli/src/args.rs

@@ -35,7 +35,7 @@ pub enum Commands {
 pub struct ProjectNewArgs {
     /// Path to the directory to create the new project in
     pub path: PathBuf,
-    /// Set the resulting crate name (defaults to the directory name)
+    /// Set the resulting crate name [default: the directory name]
     #[arg(long)]
     pub name: Option<String>,
     #[command(flatten)]
@@ -52,7 +52,7 @@ pub enum MigrationCommands {
 
 #[derive(Debug, Args)]
 pub struct MigrationListArgs {
-    /// Path to the crate directory to list migrations for  [default: current
+    /// Path to the crate directory to list migrations for [default: current
     /// directory]
     pub path: Option<PathBuf>,
 }
@@ -62,11 +62,11 @@ pub struct MigrationMakeArgs {
     /// Path to the crate directory to generate migrations for [default: current
     /// directory]
     pub path: Option<PathBuf>,
-    /// Name of the app to use in the migration (default: crate name)
+    /// Name of the app to use in the migration [default: crate name]
     #[arg(long)]
     pub app_name: Option<String>,
-    /// Directory to write the migrations to (default: migrations/ directory
-    /// in the crate's src/ directory)
+    /// Directory to write the migrations to [default: the migrations/ directory
+    /// in the crate's src/ directory]
     #[arg(long)]
     pub output_dir: Option<PathBuf>,
 }

cot-cli/src/migration_generator.rs

@@ -143,8 +143,8 @@ impl MigrationGenerator {
         Ok(migrations)
     }
 
-    /// Generate migrations and return internal structures that can be used to
-    /// generate source code.
+    /// Generates migrations and returns an intermediate structure that can be
+    /// converted into Rust source code.
     pub fn generate_migrations_as_generated_from_files(
         &self,
         source_files: Vec<SourceFile>,
@@ -829,14 +829,12 @@ impl MigrationProcessor {
         Ok(Self { migrations })
     }
 
-    /// Returns the latest (in the order of applying migrations) versions of the
-    /// models that are marked as migration models, that means the latest
-    /// version of each migration model.
+    /// Returns the most recent versions of all models found across all
+    /// migrations.
     ///
     /// This is useful for generating migrations - we can compare the latest
-    /// version of the model in the source code with the latest version of the
-    /// model in the migrations (returned by this method) and generate the
-    /// necessary operations.
+    /// version of the model in the source code with the most recent version in
+    /// the migrations and generate the necessary operations.
     #[must_use]
     fn latest_models(&self) -> Vec<ModelInSource> {
         let mut migration_models: HashMap<String, &ModelInSource> = HashMap::new();
@@ -859,10 +857,18 @@ impl MigrationProcessor {
             .name
             .split('_')
             .nth(1)
-            .with_context(|| format!("migration number not found: {}", last_migration.name))?
+            .with_context(|| {
+                format!(
+                    "the migration number was not found: {}",
+                    last_migration.name
+                )
+            })?
             .parse::<u32>()
             .with_context(|| {
-                format!("unable to parse migration number: {}", last_migration.name)
+                format!(
+                    "unable to parse the migration number: {}",
+                    last_migration.name
+                )
             })?;
 
         let migration_number = last_migration_number + 1;

cot-cli/tests/snapshot_testing/cli/snapshots/cli__snapshot_testing__cli__completions_elvish.snap

@@ -44,7 +44,7 @@ set edit:completion:arg-completer[cot] = {|@words|
             cand help 'Print this message or the help of the given subcommand(s)'
         }
         &'cot;new'= {
-            cand --name 'Set the resulting crate name (defaults to the directory name)'
+            cand --name 'Set the resulting crate name [default: the directory name]'
             cand --cot-path 'Use `cot` from the specified path instead of a published crate'
             cand --use-git 'Use the latest `cot` version from git instead of a published crate'
             cand -v 'Increase logging verbosity'
@@ -74,8 +74,8 @@ set edit:completion:arg-completer[cot] = {|@words|
             cand --help 'Print help'
         }
         &'cot;migration;make'= {
-            cand --app-name 'Name of the app to use in the migration (default: crate name)'
-            cand --output-dir 'Directory to write the migrations to (default: migrations/ directory in the crate''s src/ directory)'
+            cand --app-name 'Name of the app to use in the migration [default: crate name]'
+            cand --output-dir 'Directory to write the migrations to [default: the migrations/ directory in the crate''s src/ directory]'
             cand -v 'Increase logging verbosity'
             cand --verbose 'Increase logging verbosity'
             cand -q 'Decrease logging verbosity'

cot-cli/tests/snapshot_testing/cli/snapshots/cli__snapshot_testing__cli__completions_fish.snap

@@ -44,7 +44,7 @@ complete -c cot -n "__fish_cot_needs_command" -f -a "new" -d 'Create a new Cot p
 complete -c cot -n "__fish_cot_needs_command" -f -a "migration" -d 'Manage migrations for a Cot project'
 complete -c cot -n "__fish_cot_needs_command" -f -a "cli" -d 'Manage Cot CLI'
 complete -c cot -n "__fish_cot_needs_command" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
-complete -c cot -n "__fish_cot_using_subcommand new" -l name -d 'Set the resulting crate name (defaults to the directory name)' -r
+complete -c cot -n "__fish_cot_using_subcommand new" -l name -d 'Set the resulting crate name [default: the directory name]' -r
 complete -c cot -n "__fish_cot_using_subcommand new" -l cot-path -d 'Use `cot` from the specified path instead of a published crate' -r -F
 complete -c cot -n "__fish_cot_using_subcommand new" -l use-git -d 'Use the latest `cot` version from git instead of a published crate'
 complete -c cot -n "__fish_cot_using_subcommand new" -s v -l verbose -d 'Increase logging verbosity'
@@ -59,8 +59,8 @@ complete -c cot -n "__fish_cot_using_subcommand migration; and not __fish_seen_s
 complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from list" -s v -l verbose -d 'Increase logging verbosity'
 complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from list" -s q -l quiet -d 'Decrease logging verbosity'
 complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from list" -s h -l help -d 'Print help'
-complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -l app-name -d 'Name of the app to use in the migration (default: crate name)' -r
-complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -l output-dir -d 'Directory to write the migrations to (default: migrations/ directory in the crate\'s src/ directory)' -r -F
+complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -l app-name -d 'Name of the app to use in the migration [default: crate name]' -r
+complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -l output-dir -d 'Directory to write the migrations to [default: the migrations/ directory in the crate\'s src/ directory]' -r -F
 complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -s v -l verbose -d 'Increase logging verbosity'
 complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -s q -l quiet -d 'Decrease logging verbosity'
 complete -c cot -n "__fish_cot_using_subcommand migration; and __fish_seen_subcommand_from make" -s h -l help -d 'Print help'

cot-cli/tests/snapshot_testing/cli/snapshots/cli__snapshot_testing__cli__completions_powershell.snap

@@ -48,7 +48,7 @@ Register-ArgumentCompleter -Native -CommandName 'cot' -ScriptBlock {
             break
         }
         'cot;new' {
-            [CompletionResult]::new('--name', '--name', [CompletionResultType]::ParameterName, 'Set the resulting crate name (defaults to the directory name)')
+            [CompletionResult]::new('--name', '--name', [CompletionResultType]::ParameterName, 'Set the resulting crate name [default: the directory name]')
             [CompletionResult]::new('--cot-path', '--cot-path', [CompletionResultType]::ParameterName, 'Use `cot` from the specified path instead of a published crate')
             [CompletionResult]::new('--use-git', '--use-git', [CompletionResultType]::ParameterName, 'Use the latest `cot` version from git instead of a published crate')
             [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Increase logging verbosity')
@@ -81,8 +81,8 @@ Register-ArgumentCompleter -Native -CommandName 'cot' -ScriptBlock {
             break
         }
         'cot;migration;make' {
-            [CompletionResult]::new('--app-name', '--app-name', [CompletionResultType]::ParameterName, 'Name of the app to use in the migration (default: crate name)')
-            [CompletionResult]::new('--output-dir', '--output-dir', [CompletionResultType]::ParameterName, 'Directory to write the migrations to (default: migrations/ directory in the crate''s src/ directory)')
+            [CompletionResult]::new('--app-name', '--app-name', [CompletionResultType]::ParameterName, 'Name of the app to use in the migration [default: crate name]')
+            [CompletionResult]::new('--output-dir', '--output-dir', [CompletionResultType]::ParameterName, 'Directory to write the migrations to [default: the migrations/ directory in the crate''s src/ directory]')
             [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Increase logging verbosity')
             [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Increase logging verbosity')
             [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Decrease logging verbosity')

cot-cli/tests/snapshot_testing/cli/snapshots/cli__snapshot_testing__cli__completions_zsh.snap

@@ -46,7 +46,7 @@ _cot() {
         case $line[1] in
             (new)
 _arguments "${_arguments_options[@]}" : \
-'--name=[Set the resulting crate name (defaults to the directory name)]:NAME:_default' \
+'--name=[Set the resulting crate name \[default\: the directory name\]]:NAME:_default' \
 '--cot-path=[Use \`cot\` from the specified path instead of a published crate]:COT_PATH:_files' \
 '--use-git[Use the latest \`cot\` version from git instead of a published crate]' \
 '*-v[Increase logging verbosity]' \
@@ -84,13 +84,13 @@ _arguments "${_arguments_options[@]}" : \
 '(-v --verbose)*--quiet[Decrease logging verbosity]' \
 '-h[Print help]' \
 '--help[Print help]' \
-'::path -- Path to the crate directory to list migrations for  \[default\: current directory\]:_files' \
+'::path -- Path to the crate directory to list migrations for \[default\: current directory\]:_files' \
 && ret=0
 ;;
 (make)
 _arguments "${_arguments_options[@]}" : \
-'--app-name=[Name of the app to use in the migration (default\: crate name)]:APP_NAME:_default' \
-'--output-dir=[Directory to write the migrations to (default\: migrations/ directory in the crate'\''s src/ directory)]:OUTPUT_DIR:_files' \
+'--app-name=[Name of the app to use in the migration \[default\: crate name\]]:APP_NAME:_default' \
+'--output-dir=[Directory to write the migrations to \[default\: the migrations/ directory in the crate'\''s src/ directory\]]:OUTPUT_DIR:_files' \
 '*-v[Increase logging verbosity]' \
 '*--verbose[Increase logging verbosity]' \
 '(-v --verbose)*-q[Decrease logging verbosity]' \

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__help.snap

@@ -8,7 +8,7 @@ info:
 success: true
 exit_code: 0
 ----- stdout -----
-The Rust web framework for lazy developers - CLI tool.
+Command-line interface for the Cot web framework
 
 Usage: cot [OPTIONS] <COMMAND>
 

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__help_migration_list.snap

@@ -15,7 +15,7 @@ List all migrations for a Cot project
 Usage: cot migration list [OPTIONS] [PATH]
 
 Arguments:
-  [PATH]  Path to the crate directory to list migrations for  [default: current directory]
+  [PATH]  Path to the crate directory to list migrations for [default: current directory]
 
 Options:
   -v, --verbose...  Increase logging verbosity

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__help_migration_make.snap

@@ -18,10 +18,10 @@ Arguments:
   [PATH]  Path to the crate directory to generate migrations for [default: current directory]
 
 Options:
-      --app-name <APP_NAME>      Name of the app to use in the migration (default: crate name)
+      --app-name <APP_NAME>      Name of the app to use in the migration [default: crate name]
   -v, --verbose...               Increase logging verbosity
-      --output-dir <OUTPUT_DIR>  Directory to write the migrations to (default: migrations/
-                                 directory in the crate's src/ directory)
+      --output-dir <OUTPUT_DIR>  Directory to write the migrations to [default: the migrations/
+                                 directory in the crate's src/ directory]
   -q, --quiet...                 Decrease logging verbosity
   -h, --help                     Print help
 

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__help_new.snap

@@ -17,7 +17,7 @@ Arguments:
   <PATH>  Path to the directory to create the new project in
 
 Options:
-      --name <NAME>          Set the resulting crate name (defaults to the directory name)
+      --name <NAME>          Set the resulting crate name [default: the directory name]
   -v, --verbose...           Increase logging verbosity
   -q, --quiet...             Decrease logging verbosity
       --use-git              Use the latest `cot` version from git instead of a published crate

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__long_help.snap

@@ -8,7 +8,7 @@ info:
 success: true
 exit_code: 0
 ----- stdout -----
-The Rust web framework for lazy developers - CLI tool.
+Command-line interface for the Cot web framework
 
 Usage: cot [OPTIONS] <COMMAND>
 

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__no_args.snap

@@ -9,7 +9,7 @@ exit_code: 2
 ----- stdout -----
 
 ----- stderr -----
-The Rust web framework for lazy developers - CLI tool.
+Command-line interface for the Cot web framework
 
 Usage: cot [OPTIONS] <COMMAND>
 

cot-cli/tests/snapshot_testing/help/snapshots/cli__snapshot_testing__help__short_help.snap

@@ -8,7 +8,7 @@ info:
 success: true
 exit_code: 0
 ----- stdout -----
-The Rust web framework for lazy developers - CLI tool.
+Command-line interface for the Cot web framework
 
 Usage: cot [OPTIONS] <COMMAND>
 

cot-codegen/src/symbol_resolver.rs

@@ -163,7 +163,7 @@ impl SymbolResolver {
 /// a `use` statement for a given type, but also, for instance, the type is
 /// defined in the current module.
 ///
-/// For instance, for `use std::collections::HashMap;` the `VisibleSymbol `
+/// For instance, for `use std::collections::HashMap;` the `VisibleSymbol`
 /// would be:
 /// ```
 /// use cot_codegen::symbol_resolver::{VisibleSymbol, VisibleSymbolKind};

cot-core/src/body.rs

@@ -143,9 +143,8 @@ impl Body {
     ///
     /// # Errors
     ///
-    /// This method returns an error if reading the body fails.
-    ///
-    /// If the body is larger than the limit, an error is returned.
+    /// This method returns an error if reading the body fails, or if the body
+    /// is larger than the specified limit.
     ///
     /// # Examples
     ///

cot-core/src/handler.rs

@@ -49,8 +49,7 @@ pub trait RequestHandler<T = ()> {
     ///
     /// # Errors
     ///
-    /// This method can return an error if the request handler fails to handle
-    /// the request.
+    /// This method can return an error if it fails to handle the request.
     fn handle(&self, request: Request) -> impl Future<Output = Result<Response>> + Send;
 }
 

cot-core/src/html.rs

@@ -193,7 +193,7 @@ impl HtmlTag {
     ///
     /// # Safety
     ///
-    /// This function will escape the attribute value. Note that it does not
+    /// This function escapes the attribute value. Note that it does not
     /// escape the attribute name.
     ///
     /// # Panics
@@ -226,7 +226,7 @@ impl HtmlTag {
     ///
     /// # Safety
     ///
-    /// This function will not escape the attribute name.
+    /// This function does not escape the attribute name.
     ///
     /// # Panics
     ///

cot-core/src/json.rs

@@ -7,7 +7,7 @@
 ///
 /// Note that this is just a newtype wrapper around data and does not provide
 /// any content validation. It is primarily useful as a request extractor and
-/// response type for REST-ful endpoints.
+/// response type for RESTful endpoints.
 ///
 /// # Examples
 ///

cot-core/src/response.rs

@@ -1,12 +1,12 @@
 use crate::{Body, StatusCode};
-
 mod into_response;
 
 /// Derive macro for the [`IntoResponse`] trait.
 ///
 /// This macro can be applied to enums to automatically implement the
 /// [`IntoResponse`] trait. The enum must consist of tuple variants with
-/// exactly one field each, where each field type implements [`IntoResponse`].
+/// exactly one field each, with each variant containing a single field that
+/// implements [`IntoResponse`].
 ///
 /// # Requirements
 ///
@@ -68,7 +68,7 @@ mod private {
 }
 
 /// Extension trait for [`http::Response`] that provides helper methods for
-/// working with HTTP response.
+/// working with HTTP responses.
 ///
 /// # Sealed
 ///
@@ -95,7 +95,7 @@ pub trait ResponseExt: Sized + private::Sealed {
     ///
     /// This creates a new [`Response`] object with a status code of
     /// [`StatusCode::SEE_OTHER`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/303)
-    /// and a location header set to the provided location.
+    /// and a `Location` header set to the provided location.
     ///
     /// # Examples
     ///

cot-macros/src/lib.rs

@@ -72,15 +72,19 @@ pub fn derive_admin_model(input: TokenStream) -> TokenStream {
 ///   use this type; the migration engine will generate the migration model
 ///   types for you.
 ///
-///   Migration models have two major uses. The first is so that the migration
-///   engine uses knows what was the state of model at the time the last
+///   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. The second use is
-///   to allow custom code in the migrations: you might want the migration to
-///   fill in some data, for instance. 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.
+///   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. After the migration has been created, though, the model
+///   might have changed. If you tried to use the application model in the
+///   migration code (which always represents the latest state of the model), it
+///   might not match the actual database schema at the time the migration is
+///   applied. You can use the migration model to ensure that your custom code
+///   operates exactly on the schema that is present at the time the migration
+///   is applied.
+///
 /// ```
 /// // In a migration file
 /// use cot::db::model;
@@ -168,7 +172,7 @@ pub fn cachetest(_args: TokenStream, input: TokenStream) -> TokenStream {
 /// An attribute macro that defines an `async` test function for a Cot-powered
 /// app.
 ///
-/// This is pretty much an equivalent to `#[tokio::test]` provided so that you
+/// This is equivalent to `#[tokio::test]`, but is provided so that you
 /// don't have to declare `tokio` as a dependency in your tests.
 ///
 /// # Examples