docs update

docs/api.rst

@@ -30,4 +30,5 @@ API Reference
    serialization_deserialization
    channels
    interop
-   shared_memory
+   shared_memory
+   ext

docs/ext.rst

@@ -0,0 +1,21 @@
+..
+.. Copyright (c) 2024 ZettaScale Technology
+..
+.. This program and the accompanying materials are made available under the
+.. terms of the Eclipse Public License 2.0 which is available at
+.. http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+.. which is available at https://www.apache.org/licenses/LICENSE-2.0.
+..
+.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+..
+.. Contributors:
+..   ZettaScale Zenoh Team, <[email protected]>
+..
+
+Extensions
+==========
+Extra functionality, which is not a part of core Zenoh API.
+
+.. doxygenclass:: zenoh::ext::PublicationCache
+   :members:
+   :membergroups: Constructors Operators Methods

include/zenoh/api/bytes.hxx

@@ -188,7 +188,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
         int64_t tell() { return ::z_bytes_reader_tell(&this->_0); }
 
         /// @brief Return the number of bytes that can still be read.
-        /// @return Number of bytes that can still be read.
+        /// @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
@@ -256,7 +256,7 @@ class Bytes : public Owned<::z_owned_bytes_t> {
         }
 
         /// @brief Finalize all writes and return underlying ``Bytes`` object.
-        /// @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));

include/zenoh/api/ext/publication_cache.hxx

@@ -31,6 +31,8 @@ class PublicationCache : public Owned<::ze_owned_publication_cache_t> {
     friend struct interop::detail::Converter;
 
    public:
+    /// @name Methods
+
     /// @brief Get the key expression of the publication cache.
     const KeyExpr& get_keyexpr() const {
         return interop::as_owned_cpp_ref<KeyExpr>(::ze_publication_cache_keyexpr(interop::as_loaned_c_ptr(*this)));

include/zenoh/api/interop.hxx

@@ -53,14 +53,14 @@ const CopyableType* as_copyable_c_ptr(const Copyable<CopyableType>& cpp_obj) {
 }
 
 /// @brief Get zenoh-c representation of std::optional of trivially copyable zenoh-cpp object.
-/// @return Pointer to zenoh-c representation of trivially copyable zenoh-cpp object, or NULL if cpp_obj is empty.
+/// @return pointer to zenoh-c representation of trivially copyable zenoh-cpp object, or NULL if cpp_obj is empty.
 template <class CopyableCppObj>
 auto* as_copyable_c_ptr(std::optional<CopyableCppObj>& cpp_obj) {
     return cpp_obj.has_value() ? as_copyable_c_ptr(cpp_obj.value()) : nullptr;
 }
 
 /// @brief Get zenoh-c representation of std::optional of trivially copyable zenoh-cpp object.
-/// @return Pointer to zenoh-c representation of trivially copyable zenoh-cpp object, or NULL if cpp_obj is empty.
+/// @return pointer to zenoh-c representation of trivially copyable zenoh-cpp object, or NULL if cpp_obj is empty.
 template <class CopyableCppObj>
 const auto* as_copyable_c_ptr(const std::optional<CopyableCppObj>& cpp_obj) {
     return cpp_obj.has_value() ? as_copyable_c_ptr(cpp_obj.value()) : nullptr;
@@ -91,7 +91,7 @@ const Loaned* as_loaned_c_ptr(const Owned<OwnedType>& cpp_obj) {
 }
 
 /// @brief Get loaned zenoh-c representation of owned zenoh-cpp object.
-/// @return Pointer to zenoh-c representation of loaned zenoh-cpp object, or NULL if cpp_obj is empty.
+/// @return pointer to zenoh-c representation of loaned zenoh-cpp object, or NULL if cpp_obj is empty.
 template <class OwnedCppObj>
 const auto* as_loaned_c_ptr(const std::optional<OwnedCppObj>& cpp_obj) {
     return cpp_obj.has_value() ? as_loaned_c_ptr(*cpp_obj) : nullptr;
@@ -109,7 +109,7 @@ Loaned* as_loaned_c_ptr(Owned<OwnedType>& cpp_obj) {
 }
 
 /// @brief Get loaned zenoh-c representation of owned zenoh-cpp object.
-/// @return Pointer to zenoh-c representation of loaned zenoh-cpp object, or NULL if cpp_obj is empty.
+/// @return pointer to zenoh-c representation of loaned zenoh-cpp object, or NULL if cpp_obj is empty.
 template <class OwnedCppObj>
 auto* as_loaned_c_ptr(std::optional<OwnedCppObj>& cpp_obj) {
     return cpp_obj.has_value() ? as_loaned_c_ptr(*cpp_obj) : nullptr;
@@ -122,7 +122,7 @@ auto* as_moved_c_ptr(Owned<OwnedType>& cpp_obj) {
 }
 
 /// @brief Get moved zenoh-c representation of std::optional of owned zenoh-cpp object.
-/// @return Pointer to zenoh-c representation of moved owned zenoh-cpp object, or NULL if cpp_obj is empty.
+/// @return pointer to zenoh-c representation of moved owned zenoh-cpp object, or NULL if cpp_obj is empty.
 template <class OwnedCppObj>
 auto* as_moved_c_ptr(std::optional<OwnedCppObj>& cpp_obj) {
     return cpp_obj.has_value() ? ::z_move(*as_owned_c_ptr(cpp_obj.value())) : nullptr;

include/zenoh/api/reply.hxx

@@ -29,13 +29,13 @@ class ReplyError : public Owned<::z_owned_reply_err_t> {
     /// @name Methods
 
     /// @brief The payload of this error.
-    /// @return Error payload.
+    /// @return error payload.
     const Bytes& get_payload() const {
         return interop::as_owned_cpp_ref<Bytes>(::z_reply_err_payload(interop::as_loaned_c_ptr(*this)));
     }
 
     /// @brief The encoding of this error.
-    /// @return Error encoding.
+    /// @return error encoding.
     const Encoding& get_encoding() const {
         return interop::as_owned_cpp_ref<Encoding>(::z_reply_err_encoding(interop::as_loaned_c_ptr(*this)));
     }
@@ -54,7 +54,7 @@ class Reply : public Owned<::z_owned_reply_t> {
     bool is_ok() const { return ::z_reply_is_ok(interop::as_loaned_c_ptr(*this)); }
 
     /// @brief Get the reply sample. Will throw a ZException if ``Reply::is_ok`` returns ``false``.
-    /// @return Reply sample.
+    /// @return reply sample.
     const Sample& get_ok() const {
         if (!::z_reply_is_ok(interop::as_loaned_c_ptr(*this))) {
             throw ZException("Reply data sample was requested, but reply contains error", Z_EINVAL);
@@ -63,7 +63,7 @@ class Reply : public Owned<::z_owned_reply_t> {
     }
 
     /// @brief Get the reply error. Will throw a ZException if ``Reply::is_ok`` returns ``true``.
-    /// @return Reply error.
+    /// @return reply error.
     const ReplyError& get_err() const {
         if (::z_reply_is_ok(interop::as_loaned_c_ptr(*this))) {
             throw ZException("Reply error was requested, but reply contains data sample", Z_EINVAL);

include/zenoh/api/session.hxx

@@ -144,7 +144,7 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param key_expr ``KeyExpr`` to declare.
     /// @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 Declared ``KeyExpr`` instance.
+    /// @return declared ``KeyExpr`` instance.
     KeyExpr declare_keyexpr(const KeyExpr& key_expr, ZResult* err = nullptr) const {
         KeyExpr k = interop::detail::null<KeyExpr>();
         __ZENOH_RESULT_CHECK(::z_declare_keyexpr(interop::as_loaned_c_ptr(*this), interop::as_owned_c_ptr(k),
@@ -1037,7 +1037,7 @@ class Session : public Owned<::z_owned_session_t> {
     /// @param options: Additional options for the publication cache.
     /// @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 Declared ``zenoh::ext::PublicationCache`` instance.
+    /// @return declared ``zenoh::ext::PublicationCache`` instance.
     [[nodiscard]] ext::PublicationCache declare_publication_cache(
         const KeyExpr& key_expr, PublicationCacheOptions&& options = PublicationCacheOptions::create_default(),
         ZResult* err = nullptr) {

include/zenoh/api/timestamp.hxx

@@ -33,7 +33,7 @@ class Timestamp : public Copyable<::z_timestamp_t> {
     /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
     /// release.
     /// @brief Get the unique id of the timestamp.
-    /// @return Id associated with this timestamp.
+    /// @return session id associated with this timestamp.
     Id get_id() const { return interop::into_copyable_cpp_obj<Id>(::z_timestamp_id(&this->inner())); }
 };