diff --git a/framework/console/controllers/BaseMigrateController.php b/framework/console/controllers/BaseMigrateController.php
index 36eda056bc..11218a459f 100644
--- a/framework/console/controllers/BaseMigrateController.php
+++ b/framework/console/controllers/BaseMigrateController.php
@@ -467,6 +467,11 @@ abstract class BaseMigrateController extends Controller
      *
      * @param string $name the name of the new migration. This should only contain
      * letters, digits and/or underscores.
+     * 
+     * Note: If the migration name is of a special form, for example create_xxx or
+     * drop_xxx then the generated migration file will contain extra code,
+     * in this case for creating/dropping tables.
+     *
      * @throws Exception if the name argument is invalid.
      */
     public function actionCreate($name)
diff --git a/framework/console/controllers/MigrateController.php b/framework/console/controllers/MigrateController.php
index 8c1c363332..7bcc43bcb9 100644
--- a/framework/console/controllers/MigrateController.php
+++ b/framework/console/controllers/MigrateController.php
@@ -92,8 +92,14 @@ class MigrateController extends BaseMigrateController
 
     /**
      * @var array column definition strings used for creating migration code.
-     * The format of each definition is `COLUMN_NAME:COLUMN_TYPE:COLUMN_DECORATOR`.
-     * For example, `--fields=name:string(12):notNull` produces a string column of size 12 which is not null.
+     *
+     * The format of each definition is `COLUMN_NAME:COLUMN_TYPE:COLUMN_DECORATOR`. Delimiter is `,`.
+     * For example, `--fields="name:string(12):notNull:unique"`
+     * produces a string column of size 12 which is not null and unique values.
+     *
+     * Note: primary key is added automatically and is named id by default.
+     * If you want to use another name you may specify it explicitly like
+     * `--fields="id_key:primaryKey,name:string(12):notNull:unique"`
      * @since 2.0.7
      */
     public $fields = [];