run/runasync docs

Author: perazz

doc/specs/stdlib_system.md

@@ -9,7 +9,7 @@ and monitoring of system commands or applications directly from Fortran.
 
 [TOC]
 
-## `run` - Execute an external process
+## `run` - Execute an external process synchronously
 
 ### Status
 
@@ -18,18 +18,57 @@ Experimental
 ### Description
 
 The `run` interface allows execution of external processes using a single command string or a list of arguments.  
-Processes can be run either synchronously (blocking execution until the process finishes) or asynchronously (non-blocking execution).  
+Processes run synchronously, meaning execution is blocked until the process finishes.  
 Optional arguments enable the collection of standard output and error streams, as well as sending input via standard input.
 
 ### Syntax
 
-`process = ` [[stdlib_subprocess(module):run(interface)]] `(args [, wait] [, stdin] [, want_stdout] [, want_stderr])`
+`process = ` [[stdlib_subprocess(module):run(interface)]] `(args [, stdin] [, want_stdout] [, want_stderr])`
 
 ### Arguments
 
 `args`: Shall be a `character(*)` string (for command-line execution) or a `character(*), dimension(:)` array (for argument-based execution). It specifies the command and arguments to execute. This is an `intent(in)` argument.
 
-`wait` (optional): Shall be a `logical` flag. If `.true.` (default), the process will execute synchronously (blocking). If `.false.`, the process will execute asynchronously (non-blocking). This is an `intent(in)` argument.
+`stdin` (optional): Shall be a `character(*)` value containing input to send to the process via standard input (pipe). This is an `intent(in)` argument.
+
+`want_stdout` (optional): Shall be a `logical` flag. If `.true.`, the standard output of the process will be captured; if `.false.` (default), it will be lost. This is an `intent(in)` argument.
+
+`want_stderr` (optional): Shall be a logical flag. If `.true.`, the standard error output of the process will be captured. Default: `.false.`. This is an `intent(in)` argument.
+
+### Return Value
+
+Returns an object of type `process_type` that contains information about the state of the created process.
+
+### Example
+
+```fortran
+! Example usage with command line or list of arguments
+type(process_type) :: p
+
+! Run a simple command line synchronously
+p = run("echo 'Hello, world!'", want_stdout=.true.)
+```
+
+
+## `runasync` - Execute an external process asynchronously
+
+### Status
+
+Experimental
+
+### Description
+
+The `runasync` interface allows execution of external processes using a single command string or a list of arguments.  
+Processes are run asynchronously (non-blocking), meaning execution does not wait for the process to finish.  
+Optional arguments enable the collection of standard output and error streams, as well as sending input via standard input.
+
+### Syntax
+
+`process = ` [[stdlib_subprocess(module):runasync(interface)]] `(args [, stdin] [, want_stdout] [, want_stderr])`
+
+### Arguments
+
+`args`: Shall be a `character(*)` string (for command-line execution) or a `character(*), dimension(:)` array (for argument-based execution). It specifies the command and arguments to execute. This is an `intent(in)` argument.
 
 `stdin` (optional): Shall be a `character(*)` value containing input to send to the process via standard input (pipe). This is an `intent(in)` argument.
 
@@ -47,11 +86,11 @@ Returns an object of type `process_type` that contains information about the sta
 ! Example usage with command line or list of arguments
 type(process_type) :: p(2)
 
-! Run a simple command line synchronously
-p(1) = run("echo 'Hello, world!'", wait=.true., want_stdout=.true.)
+! Run a simple command line asynchronously
+p(1) = runasync("echo 'Hello, world!'", want_stdout=.true.)
 
 ! Run a command using an argument list asynchronously
-p(2) = run(["/usr/bin/ls", "-l"], wait=.false.)
+p(2) = runasync(["/usr/bin/ls", "-l"], want_stdout=.true.)
 ```
 
 ## `is_running` - Check if a process is still running

src/stdlib_system.F90

@@ -57,19 +57,18 @@ module stdlib_system
 interface runasync
     !! version: experimental
     !!
-    !! Executes an external process, either synchronously or asynchronously.
-    !! ([Specification](../page/specs/stdlib_system.html#run-execute-an-external-process))
+    !! Executes an external process asynchronously.
+    !! ([Specification](../page/specs/stdlib_system.html#run-execute-an-external-process-asynchronously))
     !!
     !! ### Summary
-    !! Provides methods for executing external processes via a single command string or an argument list, 
-    !! with options for synchronous or asynchronous execution and output collection.
+    !! Provides methods for executing external processes asynchronously, using either a single command string 
+    !! or an argument list, with options for output collection and standard input.
     !!
     !! ### Description
     !! 
-    !! This interface allows the user to spawn external processes using either a single command string 
-    !! or a list of arguments. Processes can be executed synchronously (blocking) or asynchronously 
-    !! (non-blocking), with optional request to collect standard output and error streams, or to provide
-    !! a standard input stream via a `character` string.
+    !! This interface allows the user to spawn external processes asynchronously (non-blocking). 
+    !! Processes can be executed via a single command string or a list of arguments, with options to collect 
+    !! standard output and error streams, or to provide a standard input stream via a `character` string.
     !!
     !! @note The implementation depends on system-level process management capabilities.
     !!
@@ -103,19 +102,18 @@ end function run_async_args
 interface run
     !! version: experimental
     !!
-    !! Executes an external process, either synchronously or asynchronously.
-    !! ([Specification](../page/specs/stdlib_system.html#run-execute-an-external-process))
+    !! Executes an external process synchronously.
+    !! ([Specification](../page/specs/stdlib_system.html#runasync-execute-an-external-process-synchronously))
     !!
     !! ### Summary
-    !! Provides methods for executing external processes via a single command string or an argument list, 
-    !! with options for synchronous or asynchronous execution and output collection.
+    !! Provides methods for executing external processes synchronously, using either a single command string 
+    !! or an argument list, with options for output collection and standard input.
     !!
     !! ### Description
     !! 
-    !! This interface allows the user to spawn external processes using either a single command string 
-    !! or a list of arguments. Processes can be executed synchronously (blocking) or asynchronously 
-    !! (non-blocking), with optional request to collect standard output and error streams, or to provide
-    !! a standard input stream via a `character` string.
+    !! This interface allows the user to spawn external processes synchronously (blocking), 
+    !! via either a single command string or a list of arguments. It also includes options to collect 
+    !! standard output and error streams, or to provide a standard input stream via a `character` string.
     !!
     !! @note The implementation depends on system-level process management capabilities.
     !!