document wait

Author: perazz

doc/specs/stdlib_system.md

@@ -161,7 +161,7 @@ The result is a real value representing the elapsed time in seconds, measured fr
 
 ### Syntax
 
-`delta_t = ` [[stdlib_subprocess(module):elapsed(interface)]] `(process)`
+`delta_t = ` [[stdlib_subprocess(module):elapsed(subroutine)]] `(process)`
 
 ### Arguments
 
@@ -189,4 +189,46 @@ delta_t = elapsed(p)
 print *, "Elapsed time (s): ", delta_t
 ```
 
+## `wait` - Wait until a running process is completed
 
+### Status
+
+Experimental
+
+### Description
+
+The `wait` interface provides a method to block the calling program until the specified process completes.  
+If the process is running asynchronously, this subroutine will pause the workflow until the given process finishes.  
+Additionally, an optional maximum wait time can be provided. If the process does not finish within the specified time, 
+the subroutine will return without waiting further.
+
+On return from this routine, the process state is accordingly updated.
+This is useful when you want to wait for a background task to complete, but want to avoid indefinite blocking 
+in case of process hang or delay.
+
+
+### Syntax
+
+`call ` [[stdlib_subprocess(module):wait(subroutine)]] `(process [, max_wait_time])`
+
+### Arguments
+
+`process`: Shall be a `type(process_type)` object representing the external process to monitor.  
+This is an `intent(inout)` argument, and its state is updated upon completion.
+
+`max_wait_time` (optional): Shall be a `real` value specifying the maximum wait time in seconds.  
+If not provided, the subroutine will wait indefinitely until the process completes.
+
+### Example
+
+```fortran
+! Example usage of wait
+type(process_type) :: p
+
+! Start an asynchronous process
+p = run("sleep 5", wait=.false.)
+
+! Wait for process to complete with a 10-second timeout
+call wait(p, max_wait_time=10.0)
+print *, "Process completed or timed out."
+```

src/stdlib_system.F90

@@ -177,15 +177,33 @@ end function process_lifetime
 end interface elapsed
 
 
-!> Wait until a running process is completed
 interface wait
+    !! version: experimental
+    !!
+    !! Waits for a running process to complete.
+    !! ([Specification](../page/specs/stdlib_system.html#wait-wait-until-a-running-process-is-completed))
+    !!
+    !! ### Summary
+    !! Provides a method to block the execution and wait until the specified process finishes.
+    !! Supports an optional maximum wait time, after which the function returns regardless of process completion.
+    !!
+    !! ### Description
+    !! 
+    !! This interface allows waiting for a process to complete. If the process is running asynchronously, this subroutine
+    !! will block further execution until the process finishes. Optionally, a maximum wait time can be specified; if 
+    !! the process doesn't complete within this time, the subroutine returns without further waiting.
+    !!
+    !! @note The process state is accordingly updated on return from this call.
+    !!
     module subroutine wait_for_completion(process, max_wait_time)
+        !> The process object to monitor.
         class(process_type), intent(inout) :: process
-        ! Optional max wait time in seconds
+        !> Optional maximum wait time in seconds. If not provided, waits indefinitely.
         real, optional, intent(in) :: max_wait_time
     end subroutine wait_for_completion
 end interface wait
 
+
 !> Query the system to update a process's state 
 interface update
     module subroutine update_process_state(process)