Document 'positional-only' arguments (#409)

traits_futures/background_call.py

@@ -85,14 +85,18 @@ def background_task(self):
 
 def submit_call(executor, callable, *args, **kwargs):
     """
-    Convenience function to submit a background call to an executor.
+    Submit a simple call to an executor.
 
     Parameters
     ----------
     executor : TraitsExecutor
-        Executor to submit the task to.
+        Executor to submit the task to. This argument should always be passed
+        by position rather than by name. Future versions of the library may
+        enforce this restriction.
     callable
-        Callable to execute in the background.
+        Callable to execute in the background. This argument should always be
+        passed by position rather than by name. Future versions of the library
+        may enforce this restriction.
     *args
         Positional arguments to pass to the callable.
     **kwargs

traits_futures/background_iteration.py

@@ -113,14 +113,18 @@ def background_task(self):
 
 def submit_iteration(executor, callable, *args, **kwargs):
     """
-    Convenience function to submit a background iteration to an executor.
+    Submit an iteration to an executor.
 
     Parameters
     ----------
     executor : TraitsExecutor
-        Executor to submit the task to.
+        Executor to submit the task to. This argument should always be
+        passed by position rather than by name. Future versions of the library
+        may enforce this restriction.
     callable
         Callable returning an iterator when called with the given arguments.
+        This argument should always be passed by position rather than by name.
+        Future versions of the library may enforce this restriction.
     *args
         Positional arguments to pass to the callable.
     **kwargs

traits_futures/background_progress.py

@@ -159,17 +159,20 @@ def background_task(self):
 
 def submit_progress(executor, callable, *args, **kwargs):
     """
-    Convenience function to submit a background progress call.
+    Submit a progress-reporting task to an executor.
 
     Parameters
     ----------
     executor : TraitsExecutor
-        Executor to submit the task to.
+        Executor to submit the task to. This argument should always be passed
+        by position rather than by name. Future versions of the library may
+        enforce this restriction.
     callable
         Callable that executes the progress-providing function. This callable
         must accept a "progress" named argument, in addition to the provided
-        arguments. The callable may then call the "progress" argument to
-        report progress.
+        arguments. The callable may then call the "progress" argument to report
+        progress. This argument should always be passed by position rather than
+        by name. Future versions of the library may enforce this restriction.
     *args
         Positional arguments to pass to the callable.
     **kwargs