Add docs for system functions (#716)

docs/api.rst

@@ -680,28 +680,35 @@ Time
 
 Types
 ^^^^^
-.. c:type:: z_clock_t
 .. c:type:: z_time_t
 
+A time value that is accurate to the nearest microsecond but also has a range of years.
+
+.. c:type:: z_clock_t
+
+This is like a :c:type:`z_time_t` but has nanoseconds instead of microseconds.
+
 Functions
 ^^^^^^^^^
-.. autocfunction:: platform_common.h::z_clock_now
-.. autocfunction:: platform_common.h::z_clock_elapsed_s
-.. autocfunction:: platform_common.h::z_clock_elapsed_ms
-.. autocfunction:: platform_common.h::z_clock_elapsed_us
-
 .. autocfunction:: platform_common.h::z_time_now
 .. autocfunction:: platform_common.h::z_time_elapsed_s
 .. autocfunction:: platform_common.h::z_time_elapsed_ms
 .. autocfunction:: platform_common.h::z_time_elapsed_us
 .. autocfunction:: platform_common.h::z_time_now_as_str
 
+.. autocfunction:: platform_common.h::z_clock_now
+.. autocfunction:: platform_common.h::z_clock_elapsed_s
+.. autocfunction:: platform_common.h::z_clock_elapsed_ms
+.. autocfunction:: platform_common.h::z_clock_elapsed_us
+
 
 Mutex
 -----
 Types
 ^^^^^
 
+Represents a mutual exclusion (mutex) object used to ensure exclusive access to shared resources.
+
 See details at :ref:`owned_types_concept`
 
 .. c:type:: z_owned_mutex_t
@@ -730,6 +737,14 @@ Conditional Variable
 Types
 ^^^^^
 
+Represents a condition variable, which is a synchronization primitive 
+that allows threads to wait until a particular condition occurs.
+
+A condition variable is used in conjunction with mutexes to enable threads to 
+wait for signals from other threads. When a thread calls the wait function 
+on a condition variable, it releases the associated mutex and enters a wait 
+state until another thread signals the condition variable.
+
 See details at :ref:`owned_types_concept`
 
 .. c:type:: z_owned_condvar_t
@@ -755,6 +770,14 @@ Task
 ----
 Types
 ^^^^^
+
+Represents a task that can be executed by a thread.
+
+A task is an abstraction for encapsulating a unit of work that can 
+be scheduled and executed by a thread. Tasks are typically 
+used to represent asynchronous operations, allowing the program to perform 
+multiple operations concurrently.   
+
 .. c:type:: z_owned_task_t
 .. c:type:: z_moved_task_t
 

include/zenoh-pico/system/platform_common.h

@@ -91,12 +91,44 @@ uint64_t z_random_u64(void);
 
 /**
  * Fills buffer with random data.
+ *
+ * Parameters:
+ *   buf: Pointer to the buffer that will be filled with random data.
+ *   len: Number of bytes to fill in the buffer.
  */
 void z_random_fill(void *buf, size_t len);
 
 /*------------------ Memory ------------------*/
+
+/**
+ * Allocates memory of the specified size.
+ *
+ * Parameters:
+ *   size: The number of bytes to allocate.
+ *
+ * Returns:
+ *   A pointer to the allocated memory, or NULL if the allocation fails.
+ */
 void *z_malloc(size_t size);
+
+/**
+ * Reallocates the given memory block to a new size.
+ *
+ * Parameters:
+ *   ptr: Pointer to the previously allocated memory. Can be NULL, in which case it behaves like z_malloc().
+ *   size: The new size for the memory block in bytes.
+ *
+ * Returns:
+ *   A pointer to the reallocated memory, or NULL if the reallocation fails.
+ */
 void *z_realloc(void *ptr, size_t size);
+
+/**
+ * Frees the memory previously allocated by z_malloc or z_realloc.
+ *
+ * Parameters:
+ *   ptr: Pointer to the memory to be freed. If NULL, no action is taken.
+ */
 void z_free(void *ptr);
 
 #if Z_FEATURE_MULTI_THREAD == 0
@@ -132,7 +164,10 @@ void _z_task_free(_z_task_t **task);
 z_result_t z_task_init(z_owned_task_t *task, z_task_attr_t *attr, void *(*fun)(void *), void *arg);
 
 /**
- * Joins the task and releases all allocated resources
+ * Joins the task and releases all allocated resources.
+ *
+ * Parameters:
+ *   task: Pointer to a :c:type:`z_moved_task_t` representing the task to be joined.
  *
  * Returns:
  *   ``0`` in case of success, negative error code otherwise.
@@ -142,13 +177,19 @@ z_result_t z_task_join(z_moved_task_t *task);
 /**
  * Detaches the task and releases all allocated resources.
  *
+ * Parameters:
+ *   task: Pointer to a :c:type:`z_moved_task_t` representing the task to be detached.
+ *
  * Returns:
  *   ``0`` in case of success, negative error code otherwise.
  */
 z_result_t z_task_detach(z_moved_task_t *task);
 
 /**
- * Drop the task. Same as :c:func:`z_task_detach`. Use :c:func:`z_task_join` to wait for the task completion.
+ * Drops the task. Same as :c:func:`z_task_detach`. Use :c:func:`z_task_join` to wait for the task completion.
+ *
+ * Parameters:
+ *   task: Pointer to a :c:type:`z_moved_task_t` representing the task to be dropped.
  *
  * Returns:
  *   ``0`` in case of success, negative error code otherwise.
@@ -169,40 +210,55 @@ z_result_t _z_mutex_unlock(_z_mutex_t *m);
 /**
  * Constructs a mutex.
  *
+ * Parameters:
+ *   m: Pointer to an uninitialized :c:type:`z_owned_mutex_t` that will be constructed.
+ *
  * Returns:
- * 	 0 in case of success, negative error code otherwise.
+ *   ``0`` in case of success, negative error code otherwise.
  */
 z_result_t z_mutex_init(z_owned_mutex_t *m);
 
 /**
- * Drops mutex and resets it to its gravestone state.
+ * Drops a mutex and resets it to its gravestone state.
+ *
+ * Parameters:
+ *   m: Pointer to a :c:type:`z_moved_mutex_t` that will be dropped.
  *
  * Returns:
- * 	 0 in case of success, negative error code otherwise.
+ *   ``0`` in case of success, negative error code otherwise.
  */
 z_result_t z_mutex_drop(z_moved_mutex_t *m);
 
 /**
- * Locks mutex. If mutex is already locked, blocks the thread until it aquires the lock.
+ * Locks a mutex. If the mutex is already locked, blocks the thread until it acquires the lock.
+ *
+ * Parameters:
+ *   m: Pointer to a :c:type:`z_loaned_mutex_t` that will be locked.
  *
  * Returns:
- * 	 0 in case of success, negative error code otherwise.
+ *   ``0`` in case of success, negative error code otherwise.
  */
 z_result_t z_mutex_lock(z_loaned_mutex_t *m);
 
 /**
- * Tries to lock mutex. If mutex is already locked, return immediately.
+ * Tries to lock a mutex. If the mutex is already locked, the function returns immediately.
+ *
+ * Parameters:
+ *   m: Pointer to a :c:type:`z_loaned_mutex_t` that will be locked if not already locked.
  *
  * Returns:
- * 	 0 in case of success, negative error code otherwise.
+ *   ``0`` in case of success, negative error code otherwise.
  */
 z_result_t z_mutex_try_lock(z_loaned_mutex_t *m);
 
 /**
- * Unlocks previously locked mutex. If mutex was not locked by the current thread, the behaviour is undefined.
+ * Unlocks a previously locked mutex. If the mutex was not locked by the current thread, the behavior is undefined.
+ *
+ * Parameters:
+ *   m: Pointer to a :c:type:`z_loaned_mutex_t` that will be unlocked.
  *
  * Returns:
- * 	 0 in case of success, negative error code otherwise.
+ *   ``0`` in case of success, negative error code otherwise.
  */
 z_result_t z_mutex_unlock(z_loaned_mutex_t *m);
 
@@ -217,28 +273,177 @@ z_result_t _z_condvar_signal(_z_condvar_t *cv);
 z_result_t _z_condvar_signal_all(_z_condvar_t *cv);
 z_result_t _z_condvar_wait(_z_condvar_t *cv, _z_mutex_t *m);
 
+/**
+ * Initializes a condition variable.
+ *
+ * Parameters:
+ *   cv: Pointer to an uninitialized :c:type:`z_owned_condvar_t` that will be initialized.
+ *
+ * Returns:
+ *   ``0`` if the initialization is successful, a negative value otherwise.
+ */
 z_result_t z_condvar_init(z_owned_condvar_t *cv);
+
+/**
+ * Destroys a condition variable and releases its resources.
+ *
+ * Parameters:
+ *   cv: Pointer to a :c:type:`z_moved_condvar_t` that will be destroyed.
+ *
+ * Returns:
+ *   ``0`` if the destruction is successful, a negative value otherwise.
+ */
 z_result_t z_condvar_drop(z_moved_condvar_t *cv);
 
+/**
+ * Signals (wakes up) one thread waiting on the condition variable.
+ *
+ * Parameters:
+ *   cv: Pointer to a :c:type:`z_loaned_condvar_t` that will be signaled.
+ *
+ * Returns:
+ *   ``0`` if the signal is successful, a negative value otherwise.
+ */
 z_result_t z_condvar_signal(z_loaned_condvar_t *cv);
+
+/**
+ * Waits for a signal on the condition variable while holding a mutex.
+ *
+ * The calling thread is blocked until the condition variable is signaled.
+ * The associated mutex must be locked by the calling thread, and it will be automatically unlocked while waiting.
+ *
+ * Parameters:
+ *   cv: Pointer to a :c:type:`z_loaned_condvar_t` on which to wait.
+ *   m: Pointer to a :c:type:`z_loaned_mutex_t` that will be unlocked during the wait.
+ *
+ * Returns:
+ *   ``0`` if the wait is successful, a negative value otherwise.
+ */
 z_result_t z_condvar_wait(z_loaned_condvar_t *cv, z_loaned_mutex_t *m);
 
 /*------------------ Sleep ------------------*/
+/**
+ * Suspends execution for a specified amount of time in microseconds.
+ *
+ * Parameters:
+ *   time: The amount of time to sleep, in microseconds.
+ *
+ * Returns:
+ *   ``0`` if the sleep is successful, a negative value otherwise.
+ */
 z_result_t z_sleep_us(size_t time);
+
+/**
+ * Suspends execution for a specified amount of time in milliseconds.
+ *
+ * Parameters:
+ *   time: The amount of time to sleep, in milliseconds.
+ *
+ * Returns:
+ *   ``0`` if the sleep is successful, a negative value otherwise.
+ */
 z_result_t z_sleep_ms(size_t time);
+
+/**
+ * Suspends execution for a specified amount of time in seconds.
+ *
+ * Parameters:
+ *   time: The amount of time to sleep, in seconds.
+ *
+ * Returns:
+ *   ``0`` if the sleep is successful, a negative value otherwise.
+ */
 z_result_t z_sleep_s(size_t time);
 
 /*------------------ Clock ------------------*/
+/**
+ * Returns monotonic clock time point corresponding to the current time instant.
+ */
 z_clock_t z_clock_now(void);
+
+/**
+ * Returns the elapsed time in microseconds since a given clock time.
+ *
+ * Parameters:
+ *   time: Pointer to a `z_clock_t` representing the starting time.
+ *
+ * Returns:
+ *   The elapsed time in microseconds.
+ */
 unsigned long z_clock_elapsed_us(z_clock_t *time);
+
+/**
+ * Returns the elapsed time in milliseconds since a given clock time.
+ *
+ * Parameters:
+ *   time: Pointer to a `z_clock_t` representing the starting time.
+ *
+ * Returns:
+ *   The elapsed time in milliseconds.
+ */
 unsigned long z_clock_elapsed_ms(z_clock_t *time);
+
+/**
+ * Returns the elapsed time in seconds since a given clock time.
+ *
+ * Parameters:
+ *   time: Pointer to a `z_clock_t` representing the starting time.
+ *
+ * Returns:
+ *   The elapsed time in seconds.
+ */
 unsigned long z_clock_elapsed_s(z_clock_t *time);
 
 /*------------------ Time ------------------*/
+
+/**
+ * Returns system clock time point corresponding to the current time instant.
+ */
 z_time_t z_time_now(void);
+
+/**
+ * Gets the current time as a string.
+ *
+ * Parameters:
+ *   buf: Pointer to a buffer where the time string will be written.
+ *   buflen: The length of the buffer.
+ *
+ * Returns:
+ *   A pointer to the buffer containing the time string.
+ */
 const char *z_time_now_as_str(char *const buf, unsigned long buflen);
+
+/**
+ * Returns the elapsed time in microseconds since a given time.
+ *
+ * Parameters:
+ *   time: Pointer to a `z_time_t` representing the starting time.
+ *
+ * Returns:
+ *   The elapsed time in microseconds.
+ */
 unsigned long z_time_elapsed_us(z_time_t *time);
+
+/**
+ * Returns the elapsed time in milliseconds since a given time.
+ *
+ * Parameters:
+ *   time: Pointer to a `z_time_t` representing the starting time.
+ *
+ * Returns:
+ *   The elapsed time in milliseconds.
+ */
 unsigned long z_time_elapsed_ms(z_time_t *time);
+
+/**
+ * Returns the elapsed time in seconds since a given time.
+ *
+ * Parameters:
+ *   time: Pointer to a `z_time_t` representing the starting time.
+ *
+ * Returns:
+ *   The elapsed time in seconds.
+ */
 unsigned long z_time_elapsed_s(z_time_t *time);
 
 typedef struct {