From e0e8de1758b8f34bbb9f51019144dbd48efa9f13 Mon Sep 17 00:00:00 2001
From: Federico Caselli <cfederico87@gmail.com>
Date: Wed, 14 Feb 2024 20:31:16 +0100
Subject: [PATCH] Improve commands doc strings

Fixes: #1420
Change-Id: Id8626bd5bb87920abf83e5511130dbbfa8916465
---
 alembic/command.py | 39 ++++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/alembic/command.py b/alembic/command.py
index 37aa6e67..89c12354 100644
--- a/alembic/command.py
+++ b/alembic/command.py
@@ -49,7 +49,7 @@ def init(
 
     :param config: a :class:`.Config` object.
 
-    :param directory: string path of the target directory
+    :param directory: string path of the target directory.
 
     :param template: string name of the migration environment template to
      use.
@@ -174,7 +174,7 @@ def revision(
      will be applied to the structure generated by the revision process
      where it can be altered programmatically.   Note that unlike all
      the other parameters, this option is only available via programmatic
-     use of :func:`.command.revision`
+     use of :func:`.command.revision`.
 
     """
 
@@ -315,9 +315,11 @@ def merge(
 
     :param config: a :class:`.Config` instance
 
-    :param message: string message to apply to the revision
+    :param revisions: The revisions to merge.
 
-    :param branch_label: string label name to apply to the new revision
+    :param message: string message to apply to the revision.
+
+    :param branch_label: string label name to apply to the new revision.
 
     :param rev_id: hardcoded revision identifier instead of generating a new
      one.
@@ -370,9 +372,10 @@ def upgrade(
 
     :param config: a :class:`.Config` instance.
 
-    :param revision: string revision target or range for --sql mode
+    :param revision: string revision target or range for --sql mode. May be
+     ``"heads"`` to target the most recent revision(s).
 
-    :param sql: if True, use ``--sql`` mode
+    :param sql: if True, use ``--sql`` mode.
 
     :param tag: an arbitrary "tag" that can be intercepted by custom
      ``env.py`` scripts via the :meth:`.EnvironmentContext.get_tag_argument`
@@ -413,9 +416,10 @@ def downgrade(
 
     :param config: a :class:`.Config` instance.
 
-    :param revision: string revision target or range for --sql mode
+    :param revision: string revision target or range for --sql mode. May
+     be ``"base"`` to target the first revision.
 
-    :param sql: if True, use ``--sql`` mode
+    :param sql: if True, use ``--sql`` mode.
 
     :param tag: an arbitrary "tag" that can be intercepted by custom
      ``env.py`` scripts via the :meth:`.EnvironmentContext.get_tag_argument`
@@ -449,12 +453,13 @@ def downgrade(rev, context):
         script.run_env()
 
 
-def show(config, rev):
+def show(config: Config, rev: str) -> None:
     """Show the revision(s) denoted by the given symbol.
 
     :param config: a :class:`.Config` instance.
 
-    :param revision: string revision target
+    :param rev: string revision target. May be ``"current"`` to show the
+     revision(s) currently applied in the database.
 
     """
 
@@ -484,7 +489,7 @@ def history(
 
     :param config: a :class:`.Config` instance.
 
-    :param rev_range: string revision range
+    :param rev_range: string revision range.
 
     :param verbose: output in verbose mode.
 
@@ -543,7 +548,9 @@ def _display_current_history(rev, context):
         _display_history(config, script, base, head)
 
 
-def heads(config, verbose=False, resolve_dependencies=False):
+def heads(
+    config: Config, verbose: bool = False, resolve_dependencies: bool = False
+) -> None:
     """Show current available heads in the script directory.
 
     :param config: a :class:`.Config` instance.
@@ -568,7 +575,7 @@ def heads(config, verbose=False, resolve_dependencies=False):
         )
 
 
-def branches(config, verbose=False):
+def branches(config: Config, verbose: bool = False) -> None:
     """Show current branch points.
 
     :param config: a :class:`.Config` instance.
@@ -638,7 +645,9 @@ def stamp(
     :param config: a :class:`.Config` instance.
 
     :param revision: target revision or list of revisions.   May be a list
-     to indicate stamping of multiple branch heads.
+     to indicate stamping of multiple branch heads; may be ``"base"``
+     to remove all revisions from the table or ``"heads"`` to stamp the
+     most recent revision(s).
 
      .. note:: this parameter is called "revisions" in the command line
         interface.
@@ -728,7 +737,7 @@ def ensure_version(config: Config, sql: bool = False) -> None:
 
     :param config: a :class:`.Config` instance.
 
-    :param sql: use ``--sql`` mode
+    :param sql: use ``--sql`` mode.
 
      .. versionadded:: 1.7.6