doc: Add information on the required structure of the migration scripts

Author: mareq

sqlx-core/src/migrate/migrator.rs

@@ -27,6 +27,7 @@ impl Migrator {
     /// # })
     /// # }
     /// ```
+    /// See [MigrationSource] for details on structure of the `./migrations` directory.
     pub async fn new<'s, S>(source: S) -> Result<Self, MigrateError>
     where
         S: MigrationSource<'s>,

sqlx-core/src/migrate/source.rs

@@ -11,6 +11,12 @@ 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 {