improve docs about migration files (#2566)

sqlx-core/src/migrate/source.rs

@@ -7,16 +7,24 @@ use std::borrow::Cow;
 use std::fmt::Debug;
 use std::path::{Path, PathBuf};
 
+/// In the default implementation, a MigrationSource is a directory which
+/// contains the migration SQL scripts. All these scripts must be stored in
+/// files with names using the format `<VERSION>_<DESCRIPTION>.sql`, where
+/// `<VERSION>` is a string that can be parsed into `i64` and its value is
+/// greater than zero, and `<DESCRIPTION>` is a string.
+///
+/// Files that don't match this format are silently ignored.
+///
+/// You can create a new empty migration script using sqlx-cli:
+/// `sqlx migrate add <DESCRIPTION>`.
+///
+/// Note that migrations for each database are tracked using the
+/// `_sqlx_migrations` table (stored in the database). If a migration's hash
+/// changes and it has already been run, this will cause an error.
 pub trait MigrationSource<'s>: Debug {
     fn resolve(self) -> BoxFuture<'s, Result<Vec<Migration>, BoxDynError>>;
 }
 
-/// Implementation of the `MigrationSource` for [std::path::Path].
-///
-/// The path has to point to a directory, which contains the migration SQL scripts. All these
-/// scripts must be stored in files with names using the format `<VERSION>_<DESCRIPTION>.sql`,
-/// where `<VERSION>` is a string that can be parsed into `i64` and its value is greater than zero,
-/// and `<DESCRIPTION>` is a string.
 impl<'s> MigrationSource<'s> for &'s Path {
     fn resolve(self) -> BoxFuture<'s, Result<Vec<Migration>, BoxDynError>> {
         Box::pin(async move {