docs clean up (#251)

* docs clean up; add docs about shm; remove Id::is_valid(); add Id::to_string(); * addressed review comments * typo fix * put language constructs into double quotes * fix missing double quotes * typo fix
eclipse-zenoh · Oct 15, 2024 · fb2fe00 · fb2fe00
1 parent ed450f9
commit fb2fe00
Show file tree

Hide file tree

Showing 31 changed files with 300 additions and 195 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -40,7 +40,7 @@ build the documentation with this command:
 cmake --build build --target docs
 ```
 
-If everrything is ok, the output is
+If everything is ok, the output is
 ```
 ...
 See read-the-docs html in /username/build/docs/docs/sphinx/index.html

diff --git a/docs/api.rst b/docs/api.rst
@@ -29,4 +29,5 @@ API Reference
    query_reply
    serialization_deserialization
    channels
-   interop
+   interop
+   shared_memory
diff --git a/docs/channels.rst b/docs/channels.rst
@@ -17,6 +17,8 @@ Channels
 
 Classes providing stream interface for Zenoh messages.
 
+.. doxygenenum:: zenoh::channels::RecvError
+
 .. doxygenclass:: zenoh::channels::FifoChannel
     :members:
 

diff --git a/docs/commons.rst b/docs/commons.rst
@@ -76,6 +76,12 @@ Sample
    :members:
    :membergroups: Constructors Operators Methods
 
+Bytes
+------
+.. doxygenclass:: zenoh::Bytes
+   :members:
+   :membergroups: Constructors Operators Methods
+
 Logging
 -------
 

diff --git a/docs/interop.rst b/docs/interop.rst
@@ -12,8 +12,11 @@
 ..   ZettaScale Zenoh Team, <zenoh@zettascale.tech>
 ..
 
-Interoperability with Zenoh-c / Zenoh-pico
+Interoperability with zenoh-c / zenoh-pico
 ==========================================
+This is the list of the functions that can be use for interoperability between zenoh-c/zenoh-pico and
+zenoh-cpp. These functions essentially perform conversion of c-structs into c++ classes and back. They should be used with
+care, and it is up to the user to ensure that all necessary invariants uphold.
 
 .. doxygennamespace:: zenoh::interop
     :content-only:
diff --git a/docs/serialization_deserialization.rst b/docs/serialization_deserialization.rst
@@ -14,10 +14,6 @@
 
 Serialization/Deserialziation
 =============================
-.. doxygenclass:: zenoh::Bytes
-   :members:
-   :membergroups: Constructors Operators Methods
-
 .. doxygenclass:: zenoh::ext::Serializer
    :members:
    :membergroups: Constructors Operators Methods

diff --git a/docs/shared_memory.rst b/docs/shared_memory.rst
@@ -0,0 +1,75 @@
+..
+.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+..
+.. Contributors:
+..   ZettaScale Zenoh Team, <zenoh@zettascale.tech>
+..
+
+Shared Memory
+=============
+.. doxygenclass:: zenoh::ZShm
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::ZShmMut
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::CppShmClient
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::ShmClient
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::CppShmSegment
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::ShmClientStorage
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::PosixShmClient
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::PosixShmProvider
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::CppShmProvider
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::AllocLayout
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::MemoryLayout
+   :members:
+   :membergroups: Constructors Operators Methods
+
+.. doxygenclass:: zenoh::ChunkAllocResult
+   :members:
+   :membergroups: Constructors Operators Methods
+
+
+.. doxygentypedef:: zenoh::ProtocolId
+.. doxygentypedef:: zenoh::SegmentId
+.. doxygentypedef:: zenoh::ChunkId
+
+.. doxygentypedef:: zenoh::ChunkDescriptor
+.. doxygentypedef:: zenoh::AllocatedChunk
+
+.. doxygentypedef:: zenoh::AllocError
+.. doxygentypedef:: zenoh::LayoutError
+.. doxygentypedef:: zenoh::AllocAlignment
+
+.. doxygentypedef:: zenoh::BufAllocResult
+.. doxygentypedef:: zenoh::BufLayoutAllocResult
+
+.. doxygenfunction:: zenoh::cleanup_orphaned_shm_segments
+
+
diff --git a/examples/simple/Readme.md b/examples/simple/Readme.md
@@ -1,4 +1,4 @@
-# Simple CMake projects demonstrating usage of Zenoh-C++
+# Simple CMake projects demonstrating usage of zenoh-cpp
 
 * [universal](universal) - Use same C++ source for both zenoh-c and zenoh-pico
 * [zenohc](zenohc) - Explicitly use Zenoh-C library

diff --git a/include/zenoh/api/base.hxx b/include/zenoh/api/base.hxx
@@ -66,9 +66,9 @@ class Owned {
     typedef ZC_OWNED_TYPE OwnedType;
 
    public:
-    /// Move constructor from other object
+    /// Move constructor.
     Owned(Owned&& v) : Owned(&v._0) {}
-    /// Move assignment from other object
+    /// Move assignment.
     Owned& operator=(Owned&& v) {
         if (this != &v) {
             ::z_drop(::z_move(this->_0));

diff --git a/include/zenoh/api/bytes.hxx b/include/zenoh/api/bytes.hxx
@@ -165,7 +165,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
     /// The only provided guarantee is on the bytes order that is preserved.
     SliceIterator slice_iter() const;
 
-    /// @brief A reader for Zenoh-serialized data.
+    /// @brief A reader for zenoh payload.
     class Reader : public Copyable<::z_bytes_reader_t> {
         using Copyable::Copyable;
         friend struct interop::detail::Converter;
@@ -191,7 +191,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
         /// @return Number of bytes that can still be read.
         size_t remaining() const { return ::z_bytes_reader_remaining(&this->_0); }
 
-        /// @brief Set the `reader` position indicator to the value pointed to by offset, starting from the current
+        /// @brief Set the reader position indicator to the value pointed to by offset, starting from the current
         /// position.
         /// @param offset offset in bytes starting from the current position.
         /// @param err if not null, the result code will be written to this location, otherwise ZException exception
@@ -200,7 +200,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
             __ZENOH_RESULT_CHECK(::z_bytes_reader_seek(&this->_0, offset, SEEK_CUR), err, "seek_from_current failed");
         }
 
-        /// @brief Set the `reader` position indicator to the value pointed to by offset, starting from the start of the
+        /// @brief Set the reader position indicator to the value pointed to by offset, starting from the start of the
         /// data.
         /// @param offset offset in bytes starting from the 0-th byte position.
         /// @param err if not null, the result code will be written to this location, otherwise ZException exception
@@ -209,7 +209,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
             __ZENOH_RESULT_CHECK(::z_bytes_reader_seek(&this->_0, offset, SEEK_SET), err, "seek_from_start failed");
         }
 
-        /// @brief Set the `reader` position indicator to the value pointed to by offset with respect to the end of the
+        /// @brief Set the reader position indicator to the value pointed to by offset with respect to the end of the
         /// data.
         /// @param offset offset in bytes starting from end position.
         /// @param err if not null, the result code will be written to this location, otherwise ZException exception
@@ -223,7 +223,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
     /// @return reader instance.
     Reader reader() const { return Reader(*this); }
 
-    /// @brief A writer for Zenoh-serialized data.
+    /// @brief A writer for zenoh payload.
     class Writer : public Owned<::z_owned_bytes_writer_t> {
        public:
         /// @name Constructors
@@ -243,8 +243,8 @@ class Bytes : public Owned<::z_owned_bytes_t> {
                                  "Failed to write data");
         }
 
-        /// @brief Append another `Bytes` instance.
-        /// This allows to compose data out of multiple `Bytes` that may point to different memory regions.
+        /// @brief Append another ``Bytes`` instance.
+        /// This allows to compose data out of multiple ``Bytes`` that may point to different memory regions.
         /// Said in other terms, it allows to create a linear view on different memory regions without copy.
         ///
         /// @param data data to append.
@@ -255,8 +255,8 @@ class Bytes : public Owned<::z_owned_bytes_t> {
                                  "Failed to append data");
         }
 
-        /// @brief Finalize all writes and return underlying `Bytes` object.
-        /// @return Underlying `Bytes` object.
+        /// @brief Finalize all writes and return underlying ``Bytes`` object.
+        /// @return Underlying ``Bytes`` object.
         Bytes finish() && {
             Bytes b;
             ::z_bytes_writer_finish(interop::as_moved_c_ptr(*this), interop::as_owned_c_ptr(b));

diff --git a/include/zenoh/api/channels.hxx b/include/zenoh/api/channels.hxx
@@ -99,17 +99,18 @@ struct RingHandlerData<zenoh::Reply> {
 
 class FifoChannel;
 
-/// @brief A FIFO channel handler
-/// @tparam T data entry type
+/// @brief A FIFO channel handler.
+/// @tparam T data entry type.
 template <class T>
 class FifoHandler : public Owned<typename detail::FifoHandlerData<T>::handler_type> {
     FifoHandler(zenoh::detail::null_object_t) : Owned<typename detail::FifoHandlerData<T>::handler_type>(nullptr){};
 
    public:
     /// @name Methods
 
-    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty will block until new data entry arrives.
-    /// @return received data entry if there were any in the buffer, a receive error otherwise.
+    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty, will block until new data entry
+    /// arrives.
+    /// @return received data entry, if there were any in the buffer, a receive error otherwise.
     std::variant<T, RecvError> recv() const {
         std::variant<T, RecvError> v(interop::detail::null<T>());
         z_result_t res = ::z_recv(interop::as_loaned_c_ptr(*this), zenoh::interop::as_owned_c_ptr(std::get<T>(v)));
@@ -120,8 +121,8 @@ class FifoHandler : public Owned<typename detail::FifoHandlerData<T>::handler_ty
         }
     }
 
-    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty will immediately return.
-    /// @return received data entry if there were any in the buffer, a receive error otherwise.
+    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty, will immediately return.
+    /// @return received data entry, if there were any in the buffer, a receive error otherwise.
     std::variant<T, RecvError> try_recv() const {
         std::variant<T, RecvError> v(interop::detail::null<T>());
         z_result_t res = ::z_try_recv(interop::as_loaned_c_ptr(*this), zenoh::interop::as_owned_c_ptr(std::get<T>(v)));
@@ -148,8 +149,9 @@ class RingHandler : public Owned<typename detail::RingHandlerData<T>::handler_ty
    public:
     /// @name Methods
 
-    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty will block until new data entry arrives.
-    /// @return received data entry if there were any in the buffer, a receive error otherwise.
+    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty, will block until new data entry
+    /// arrives.
+    /// @return received data, entry if there were any in the buffer, a receive error otherwise.
     std::variant<T, RecvError> recv() const {
         std::variant<T, RecvError> v(interop::detail::null<T>());
         z_result_t res =
@@ -161,8 +163,8 @@ class RingHandler : public Owned<typename detail::RingHandlerData<T>::handler_ty
         }
     }
 
-    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty will immediately return.
-    /// @return received data entry if there were any in the buffer, a receive error otherwise.
+    /// @brief Fetch a data entry from the handler's buffer. If buffer is empty, will immediately return.
+    /// @return received data entry, if there were any in the buffer, a receive error otherwise.
     std::variant<T, RecvError> try_recv() const {
         std::variant<T, RecvError> v(interop::detail::null<T>());
         z_result_t res = ::z_try_recv(interop::as_loaned_c_ptr(*this), zenoh::interop::as_owned_c_ptr(std::get<T>(v)));
@@ -184,7 +186,7 @@ class FifoChannel {
 
    public:
     /// @brief Constructor.
-    /// @param capacity maximum number of entries in the FIFO buffer of the channel. When the buffer is full all
+    /// @param capacity maximum number of entries in the FIFO buffer of the channel. When the buffer is full, all
     /// new attempts to insert data will block, until an entry is fetched and the space is freed in the buffer.
     FifoChannel(size_t capacity) : _capacity(capacity) {}
 

diff --git a/include/zenoh/api/config.hxx b/include/zenoh/api/config.hxx
@@ -37,11 +37,13 @@ class Config : public Owned<::z_owned_config_t> {
 
 #ifdef ZENOHCXX_ZENOHC
     /// @brief Create the configuration from the JSON file.
-    /// @param path path to the config file.
+    /// @param path path to the config file (see <a
+    /// href="https://zenoh.io/docs/manual/configuration/#configuration-files">config file documentation</a> for more
+    /// information).
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return the ``Config`` object.
-    /// @note zenoh-c only.
+    /// @note Zenoh-c only.
     static Config from_file(const std::string& path, ZResult* err = nullptr) {
         Config c(zenoh::detail::null_object);
         __ZENOH_RESULT_CHECK(::zc_config_from_file(&c._0, path.data()), err,
@@ -54,7 +56,7 @@ class Config : public Owned<::z_owned_config_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return the ``Config`` object.
-    /// @note zenoh-c only.
+    /// @note Zenoh-c only.
     static Config from_str(const std::string& s, ZResult* err = nullptr) {
         Config c(zenoh::detail::null_object);
         __ZENOH_RESULT_CHECK(::zc_config_from_str(&c._0, s.data()), err,
@@ -66,7 +68,7 @@ class Config : public Owned<::z_owned_config_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return the ``Config`` object.
-    /// @note zenoh-pico only.
+    /// @note Zenoh-pico only.
     static Config from_env(ZResult* err = nullptr) {
         Config c(zenoh::detail::null_object);
         __ZENOH_RESULT_CHECK(::zc_config_from_env(&c._0), err, "Failed to create config from environment variable");
@@ -82,7 +84,7 @@ class Config : public Owned<::z_owned_config_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return value of the config parameter in JSON format.
-    /// @note zenoh-c only.
+    /// @note Zenoh-c only.
     std::string get(std::string_view key, ZResult* err = nullptr) const {
         ::z_owned_string_t s;
         __ZENOH_RESULT_CHECK(::zc_config_get_from_substr(interop::as_loaned_c_ptr(*this), key.data(), key.size(), &s),
@@ -94,7 +96,7 @@ class Config : public Owned<::z_owned_config_t> {
 
     /// @brief Get the whole config as a JSON string.
     /// @return string with config in json format.
-    /// @note zenoh-c only.
+    /// @note Zenoh-c only.
     std::string to_string() const {
         ::z_owned_string_t s;
         ::zc_config_to_string(interop::as_loaned_c_ptr(*this), &s);
@@ -108,8 +110,8 @@ class Config : public Owned<::z_owned_config_t> {
     /// @param value the JSON string value,
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
-    /// @return true if the parameter was inserted, false otherwise.
-    /// @note zenoh-c only.
+    /// @return ``true`` if the parameter was inserted, false otherwise.
+    /// @note Zenoh-c only.
     void insert_json5(const std::string& key, const std::string& value, ZResult* err = nullptr) {
         __ZENOH_RESULT_CHECK(::zc_config_insert_json5(interop::as_loaned_c_ptr(*this), key.c_str(), value.c_str()), err,
                              std::string("Failed to insert '")
@@ -125,7 +127,7 @@ class Config : public Owned<::z_owned_config_t> {
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
     /// @return pointer to the null-terminated string value of the config parameter.
-    /// @note zenoh-pico only.
+    /// @note Zenoh-pico only.
     const char* get(uint8_t key, ZResult* err = nullptr) const {
         const char* c = ::zp_config_get(interop::as_loaned_c_ptr(*this), key);
         __ZENOH_RESULT_CHECK((c == nullptr ? -1 : Z_OK), err,
@@ -138,7 +140,7 @@ class Config : public Owned<::z_owned_config_t> {
     /// @param value the null-terminated string value.
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
-    /// @note zenoh-pico only.
+    /// @note Zenoh-pico only.
     void insert(uint8_t key, const char* value, ZResult* err = nullptr) {
         __ZENOH_RESULT_CHECK(zp_config_insert(interop::as_loaned_c_ptr(*this), key, value), err,
                              std::string("Failed to insert '")