document update

Author: perazz

doc/specs/stdlib_system.md

@@ -232,3 +232,44 @@ p = run("sleep 5", wait=.false.)
 call wait(p, max_wait_time=10.0)
 print *, "Process completed or timed out."
 ```
+
+## `update` - Update the internal state of a process
+
+### Status
+
+Experimental
+
+### Description
+
+The `update` interface allows the internal state of a process object to be updated by querying the system.  
+After the process completes, the standard output and standard error are retrieved, if they were requested, and loaded into the `process%stdout` and `process%stderr` string variables, respectively.
+
+This is especially useful for monitoring asynchronous processes and retrieving their output after they have finished.
+
+### Syntax
+
+`call ` [[stdlib_subprocess(module):update(subroutine)]] `(process)`
+
+### Arguments
+
+`process`: Shall be a `type(process_type)` object representing the external process whose state needs to be updated.  
+This is an `intent(inout)` argument, and its internal state is updated on completion.
+
+### Example
+
+```fortran
+! Example usage of update
+type(process_type) :: p
+
+! Start an asynchronous process
+p = run("sleep 5", wait=.false., want_stdout=.true., want_stderr=.true.)
+
+! Periodically update the process state
+call update(p)
+
+! After completion, print the captured stdout and stderr
+if (p%completed) then 
+    print *, "Standard Output: ", p%stdout
+    print *, "Standard Error: ", p%stderr
+endif
+```

src/stdlib_system.F90

@@ -203,14 +203,32 @@ module subroutine wait_for_completion(process, max_wait_time)
     end subroutine wait_for_completion
 end interface wait
 
-
-!> Query the system to update a process's state 
 interface update
+    !! version: experimental
+    !!
+    !! Updates the internal state of a process variable.
+    !! ([Specification](../page/specs/stdlib_system.html#update-update-the-internal-state-of-a-process))
+    !!
+    !! ### Summary
+    !! Provides a method to query the system and update the internal state of the specified process variable.
+    !!
+    !! ### Description
+    !! 
+    !! This subroutine queries the system to retrieve and update information about the state of the process.
+    !! Once the process is completed, and if standard output or standard error were requested, their respective
+    !! data is loaded into the `process%stdout` and `process%stderr` variables. This routine is useful for keeping
+    !! track of the latest state and output of a process, particularly for asynchronous processes.
+    !!
+    !! @note This subroutine should be called periodically for asynchronous processes to check their completion
+    !! and retrieve the output.
+    !!
     module subroutine update_process_state(process)
+        !> The process object whose state needs to be updated.
         type(process_type), intent(inout) :: process
     end subroutine update_process_state
 end interface update
 
+
 ! Kill a process 
 interface kill
     module subroutine process_kill(process, success)