_frontend: more doc on parameters

2 files changed, 24 insertions, 5 deletions

diff --git a/buildstream/_frontend/complete.py b/buildstream/_frontend/complete.py
index 346ee7859..c3e371cac 100644
--- a/buildstream/_frontend/complete.py
+++ b/buildstream/_frontend/complete.py
@@ -145,7 +145,7 @@ def resolve_ctx(cli, prog_name, args):
     Parse into a hierarchy of contexts. Contexts are connected through the parent variable.
     :param cli: command definition
     :param prog_name: the program that is running
-    :param args: full list of args
+    :param args: full list of args typed before the incomplete arg
     :return: the final context/command parsed
     """
     ctx = cli.make_context(prog_name, args, resilient_parsing=True)
@@ -212,9 +212,12 @@ def is_incomplete_argument(current_params, cmd_param):
 def get_user_autocompletions(ctx, args, incomplete, cmd_param, override):
     """
     :param ctx: context associated with the parsed command
-    :param args: full list of args
-    :param incomplete: the incomplete text to autocomplete
+    :param args: full list of args typed before the incomplete arg
+    :param incomplete: the incomplete text of the arg to autocomplete
     :param cmd_param: command definition
+    :param override: a callable (cmd_param, ctx, args, incomplete) that will be
+    called to override default completion based on parameter type. Should raise
+    'CompleteUnhandled' if it could not find a completion.
     :return: all the possible user-specified completions for the param
     """
 
@@ -232,8 +235,11 @@ def get_choices(cli, prog_name, args, incomplete, override):
     """
     :param cli: command definition
     :param prog_name: the program that is running
-    :param args: full list of args
-    :param incomplete: the incomplete text to autocomplete
+    :param args: full list of args typed before the incomplete arg
+    :param incomplete: the incomplete text of the arg to autocomplete
+    :param override: a callable (cmd_param, ctx, args, incomplete) that will be
+    called to override default completion based on parameter type. Should raise
+    'CompleteUnhandled' if it could not find a completion.
     :return: all the possible completions for the incomplete
     """
     all_args = copy.deepcopy(args)
diff --git a/buildstream/_frontend/main.py b/buildstream/_frontend/main.py
index b2bf493ff..48c282f53 100644
--- a/buildstream/_frontend/main.py
+++ b/buildstream/_frontend/main.py
@@ -52,6 +52,12 @@ INDENT = 4
 
 # Special completion for completing the bst elements in a project dir
 def complete_target(ctx, args, incomplete):
+    """
+    :param ctx: context associated with the parsed command
+    :param args: full list of args typed before the incomplete arg
+    :param incomplete: the incomplete text to autocomplete
+    :return: all the possible user-specified completions for the param
+    """
     app = ctx.obj
 
     # First resolve the directory, in case there is an
@@ -92,6 +98,13 @@ def complete_target(ctx, args, incomplete):
 
 
 def override_completions(cmd_param, ctx, args, incomplete):
+    """
+    :param cmd_param: command definition
+    :param ctx: context associated with the parsed command
+    :param args: full list of args typed before the incomplete arg
+    :param incomplete: the incomplete text to autocomplete
+    :return: all the possible user-specified completions for the param
+    """
 
     # We can't easily extend click's data structures without
     # modifying click itself, so just do some weak special casing