document kill

Author: perazz

doc/specs/stdlib_system.md

@@ -273,3 +273,45 @@ if (p%completed) then
     print *, "Standard Error: ", p%stderr
 endif
 ```
+
+## `kill` - Terminate a running process
+
+### Status
+
+Experimental
+
+### Description
+
+The `kill` interface is used to terminate a running external process. It attempts to stop the process and returns a boolean flag indicating whether the operation was successful.
+This interface is useful when a process needs to be forcefully stopped, for example, if it becomes unresponsive or if its execution is no longer required.
+
+### Syntax
+
+`call ` [[stdlib_subprocess(module):kill(subroutine)]] `(process, success)`
+
+### Arguments
+
+`process`: Shall be a `type(process_type)` object representing the external process to be terminated.  
+This is an `intent(inout)` argument, and on return is updated with the terminated process state.
+
+`success`: Shall be a `logical` variable. It is set to `.true.` if the process was successfully killed, or `.false.` otherwise.
+
+### Example
+
+```fortran
+! Example usage of kill
+type(process_type) :: p
+logical :: success
+
+! Start a process asynchronously
+p = run("sleep 10", wait=.false.)
+
+! Attempt to kill the process
+call kill(p, success)
+
+if (success) then
+    print *, "Process successfully killed."
+else
+    print *, "Failed to kill the process."
+end if
+```

src/stdlib_system.F90

@@ -228,15 +228,34 @@ module subroutine update_process_state(process)
     end subroutine update_process_state
 end interface update
 
-
-! Kill a process 
 interface kill
+    !! version: experimental
+    !!
+    !! Terminates a running process.
+    !! ([Specification](../page/specs/stdlib_system.html#kill-terminate-a-running-process))
+    !!
+    !! ### Summary
+    !! Provides a method to kill or terminate a running process.
+    !! Returns a boolean flag indicating whether the termination was successful.
+    !!
+    !! ### Description
+    !! 
+    !! This interface allows for the termination of an external process that is still running.  
+    !! If the process is successfully killed, the `success` output flag is set to `.true.`, otherwise `.false.`.
+    !! This function is useful for controlling and managing processes that are no longer needed or for forcefully
+    !! stopping an unresponsive process.
+    !!
+    !! @note This operation may be system-dependent and could fail if the underlying user does not have 
+    !! the necessary rights to kill a process.
+    !!
     module subroutine process_kill(process, success)
+        !> The process object to be terminated.
         type(process_type), intent(inout) :: process
-        ! Return a boolean flag for successful operation
+        !> Boolean flag indicating whether the termination was successful.
         logical, intent(out) :: success
     end subroutine process_kill
-end interface kill    
+end interface kill
+ 
 
 !! version: experimental
 !!