document sleep

Author: perazz

doc/specs/stdlib_system.md

@@ -315,3 +315,35 @@ else
     print *, "Failed to kill the process."
 end if
 ```
+
+## `sleep` - Pause execution for a specified time in milliseconds
+
+### Status
+
+Experimental
+
+### Description
+
+The `sleep` interface pauses the execution of a program for a specified duration, given in milliseconds. 
+This routine acts as a cross-platform wrapper, abstracting the underlying platform-specific sleep implementations. 
+It ensures that the requested sleep duration is honored on both Windows and Unix-like systems.
+
+### Syntax
+
+`call ` [[stdlib_system(module):sleep(subroutine)]] `(millisec)`
+
+### Arguments
+
+`millisec`: Shall be an `integer` representing the number of milliseconds to sleep. This is an `intent(in)` argument.
+
+### Example
+
+```fortran
+! Example usage of sleep
+print *, "Starting sleep..."
+
+! Sleep for 500 milliseconds
+call sleep(500)
+
+print *, "Finished sleeping!"
+```

src/stdlib_system.F90

@@ -256,14 +256,31 @@ module subroutine process_kill(process, success)
     end subroutine process_kill
 end interface kill
 
-
-!! version: experimental
-!!
 interface sleep
+    !! version: experimental
+    !!
+    !! Pauses execution for a specified time in milliseconds.
+    !! ([Specification](../page/specs/stdlib_system.html#sleep-pause-execution-for-a-specified-time))
+    !!
+    !! ### Summary
+    !! Pauses code execution for a specified number of milliseconds. This routine is a cross-platform
+    !! wrapper around platform-specific sleep functions, providing consistent behavior on different operating systems.
+    !!
+    !! ### Description
+    !! 
+    !! This interface allows the user to pause the execution of a program for a specified duration, expressed in
+    !! milliseconds. It provides a cross-platform wrapper around native sleep functions, ensuring that the program 
+    !! will sleep for the requested amount of time on different systems (e.g., using `Sleep` on Windows or `nanosleep`
+    !! on Unix-like systems).
+    !!
+    !! @note The precision of the sleep may vary depending on the system and platform.
+    !!
     module subroutine sleep(millisec)
+        !> The number of milliseconds to pause execution for.
         integer, intent(in) :: millisec
     end subroutine sleep
-end interface sleep        
+end interface sleep
+      
 
 !! version: experimental
 !!