Start docs refactoring

eclipse-zenoh · Sep 30, 2024 · 3f4fab8 · 3f4fab8
1 parent 4a56e63
commit 3f4fab8
Show file tree

Hide file tree

Showing 11 changed files with 696 additions and 384 deletions.
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,7 +28,7 @@
 master_doc = 'index'
 extensions = ['sphinx_c_autodoc', 'sphinx_c_autodoc.napoleon']
 language = 'c'
-c_autodoc_roots = ['../include/zenoh-pico/api/']
+c_autodoc_roots = ['../include/zenoh-pico/api/', '../include/zenoh-pico/system/']
 c_autodoc_compilation_args = [
     "-DSPHINX_DOCS",
     "-DZ_FEATURE_UNSTABLE_API=1",

diff --git a/include/zenoh-pico/collections/arc_slice.h b/include/zenoh-pico/collections/arc_slice.h
@@ -22,7 +22,7 @@
 
 #include "refcount.h"
 #include "slice.h"
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 
 _Z_REFCOUNT_DEFINE(_z_slice, _z_slice)
 

diff --git a/include/zenoh-pico/system/platform.h b/include/zenoh-pico/system/platform.h
@@ -18,6 +18,6 @@
 #include <stdint.h>
 
 #include "zenoh-pico/config.h"
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 
 #endif /* ZENOH_PICO_SYSTEM_PLATFORM_H */
diff --git a/include/zenoh-pico/system/platform-common.h → include/zenoh-pico/system/platform_common.h b/include/zenoh-pico/system/platform-common.h → include/zenoh-pico/system/platform_common.h
@@ -65,10 +65,30 @@ void _z_report_system_error(int errcode);
     } while (false)
 
 /*------------------ Random ------------------*/
+
+/**
+ * Generates a random unsigned 8-bit integer.
+ */
 uint8_t z_random_u8(void);
+
+/**
+ * Generates a random unsigned 16-bit integer.
+ */
 uint16_t z_random_u16(void);
+
+/**
+ * Generates a random unsigned 32-bit integer.
+ */
 uint32_t z_random_u32(void);
+
+/**
+ * Generates a random unsigned 64-bit integer.
+ */
 uint64_t z_random_u64(void);
+
+/**
+ * Fills buffer with random data.
+ */
 void z_random_fill(void *buf, size_t len);
 
 /*------------------ Memory ------------------*/
@@ -107,11 +127,44 @@ z_result_t _z_mutex_unlock(_z_mutex_t *m);
 _Z_OWNED_TYPE_VALUE(_z_mutex_t, mutex)
 _Z_OWNED_FUNCTIONS_SYSTEM_DEF(mutex)
 
+/**
+ * Constructs a mutex.
+ *
+ * Returns:
+ * 	 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.
+ *
+ * Returns:
+ * 	 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.
+ *
+ * Returns:
+ * 	 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.
+ *
+ * Returns:
+ * 	 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.
+ *
+ * Returns:
+ * 	 0 in case of success, negative error code otherwise.
+ */
 z_result_t z_mutex_unlock(z_loaned_mutex_t *m);
 
 /*------------------ CondVar ------------------*/

diff --git a/include/zenoh-pico/utils/logging.h b/include/zenoh-pico/utils/logging.h
@@ -17,7 +17,7 @@
 
 #include <stdio.h>
 
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 
 // Logging values
 #define _Z_LOG_LVL_ERROR 1

diff --git a/src/api/api.c b/src/api/api.c
@@ -37,7 +37,7 @@
 #include "zenoh-pico/session/resource.h"
 #include "zenoh-pico/session/subscription.h"
 #include "zenoh-pico/session/utils.h"
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 #include "zenoh-pico/system/platform.h"
 #include "zenoh-pico/transport/multicast.h"
 #include "zenoh-pico/transport/unicast.h"

diff --git a/src/system/arduino/esp32/system.c b/src/system/arduino/esp32/system.c
@@ -19,7 +19,7 @@
 #include <sys/time.h>
 
 #include "zenoh-pico/config.h"
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 #include "zenoh-pico/system/platform.h"
 #include "zenoh-pico/utils/result.h"
 

diff --git a/src/system/platform-common.c b/src/system/platform-common.c
@@ -11,7 +11,7 @@
 // Contributors:
 //   ZettaScale Zenoh Team, <[email protected]>
 
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 
 #include "zenoh-pico/api/olv_macros.h"
 #include "zenoh-pico/utils/logging.h"

diff --git a/src/system/unix/system.c b/src/system/unix/system.c
@@ -17,7 +17,7 @@
 #include <stdlib.h>
 #include <time.h>
 
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 #include "zenoh-pico/utils/result.h"
 
 #if defined(ZENOH_LINUX)

diff --git a/tests/z_refcount_test.c b/tests/z_refcount_test.c
@@ -18,7 +18,7 @@
 #include <string.h>
 
 #include "zenoh-pico/collections/refcount.h"
-#include "zenoh-pico/system/platform-common.h"
+#include "zenoh-pico/system/platform_common.h"
 
 #undef NDEBUG
 #include <assert.h>