mark unstable features in the docs

include/zenoh/api/enums.hxx

@@ -99,7 +99,8 @@ inline std::string_view whatami_as_str(WhatAmI whatami) {
 }
 
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
-/// The locality of samples to be received by subscribers or targeted by publishers.
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief The locality of samples to be received by subscribers or targeted by publishers.
 ///
 /// Values:
 /// - **ZC_LOCALITY_ANY**:  Any.

include/zenoh/api/hello.hxx

@@ -31,6 +31,8 @@ class Hello : public Owned<::z_owned_hello_t> {
     /// @name Methods
 
 #if defined UNSTABLE
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Get ``Id`` of the entity.
     /// @return ``Id`` of the entity.
     Id get_id() const { return interop::into_copyable_cpp_obj<Id>(::z_hello_zid(interop::as_loaned_c_ptr(*this))); };

include/zenoh/api/id.hxx

@@ -22,6 +22,7 @@
 #include "interop.hxx"
 
 namespace zenoh {
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief A representation a Zenoh ID.
 ///
 /// In general, valid Zenoh IDs are LSB-first 128bit unsigned and non-zero integers.
@@ -40,6 +41,7 @@ class Id : public Copyable<::z_id_t> {
     const std::array<uint8_t, 16>& bytes() const { return *reinterpret_cast<const std::array<uint8_t, 16>*>(&_0.id); }
 };
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief Print ``Id`` in the hex format.
 inline std::ostream& operator<<(std::ostream& os, const Id& id) {
     auto id_ptr = reinterpret_cast<const ::z_id_t*>(&id)->id;

include/zenoh/api/keyexpr.hxx

@@ -120,8 +120,9 @@ class KeyExpr : public Owned<::z_owned_keyexpr_t> {
         return ::z_keyexpr_intersects(interop::as_loaned_c_ptr(*this), interop::as_loaned_c_ptr(other));
     }
 #if defined(UNSTABLE)
-    ///
-    /// Intersection level of 2 key expressions.
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
+    /// @brief Intersection level of 2 key expressions.
     ///
     /// Values:
     /// - **Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT**:  2 key expression do not intersect.

include/zenoh/api/liveliness.hxx

@@ -20,7 +20,8 @@ namespace zenoh {
 
 class Session;
 
-/// @brief // A liveliness token that can be used to provide the network with information about connectivity to its
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief A liveliness token that can be used to provide the network with information about connectivity to its
 /// declarer.
 ///
 /// When constructed, a PUT sample will be received by liveliness subscribers on intersecting key expressions.

include/zenoh/api/publisher.hxx

@@ -44,6 +44,8 @@ class Publisher : public Owned<::z_owned_publisher_t> {
         /// @brief the timestamp of this message.
         std::optional<Timestamp> timestamp = {};
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The source info of this message.
         std::optional<SourceInfo> source_info = {};
 #endif
@@ -107,6 +109,8 @@ class Publisher : public Owned<::z_owned_publisher_t> {
     }
 #endif
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Get the id of the publisher.
     /// @return id of this publisher.
     EntityGlobalId get_id() const {

include/zenoh/api/query.hxx

@@ -94,6 +94,8 @@ class Query : public Owned<::z_owned_query_t> {
         /// @brief The timestamp of this message.
         std::optional<Timestamp> timestamp = {};
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The source info of this reply message.
         std::optional<SourceInfo> source_info = {};
 #endif
@@ -171,6 +173,8 @@ class Query : public Owned<::z_owned_query_t> {
         /// @brief the timestamp of this message.
         std::optional<Timestamp> timestamp = {};
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The source info of this reply message.
         std::optional<SourceInfo> source_info = {};
 #endif

include/zenoh/api/reply.hxx

@@ -72,6 +72,8 @@ class Reply : public Owned<::z_owned_reply_t> {
     }
 
 #if defined(UNSTABLE)
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Get the id of the Zenoh instance that issued this reply.
     /// @return Zenoh instance id, or an empty optional if the id was not set.
     std::optional<Id> get_replier_id() const {

include/zenoh/api/sample.hxx

@@ -91,13 +91,17 @@ class Sample : public Owned<::z_owned_sample_t> {
     /// @return ``CongestionControl`` value.
     bool get_express() const { return ::z_sample_express(interop::as_loaned_c_ptr(*this)); }
 #if defined(ZENOHCXX) && defined(UNSTABLE)
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Get the source info of this sample.
     const SourceInfo& get_source_info() const {
         return interop::as_owned_cpp_ref<SourceInfo>(::z_sample_source_info(interop::as_loaned_c_ptr(*this)));
     }
 #endif
 
 #if defined(UNSTABLE)
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Get the reliability this sample was sent with.
     /// @return ``Reliability`` value.
     Reliability reliability() const { return ::z_sample_reliability(interop::as_loaned_c_ptr(*this)); }

include/zenoh/api/session.hxx

@@ -131,6 +131,8 @@ class Session : public Owned<::z_owned_session_t> {
     }
 
 #if defined UNSTABLE
+    /// @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 identifier of the zenoh node associated to this ``Session``.
     /// @return the unique identifier ``Id``.
     Id get_zid() const { return interop::into_copyable_cpp_obj<Id>(::z_info_zid(interop::as_loaned_c_ptr(*this))); }
@@ -178,6 +180,8 @@ class Session : public Owned<::z_owned_session_t> {
         /// @brief  An optional encoding of the query payload and/or attachment.
         std::optional<Encoding> encoding = {};
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The source info for the query.
         std::optional<SourceInfo> source_info = {};
 #endif
@@ -278,6 +282,8 @@ class Session : public Owned<::z_owned_session_t> {
         /// @brief Whether Zenoh will NOT wait to batch delete message with others to reduce the bandwith.
         bool is_express = false;
 #if defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The delete operation reliability.
         Reliability reliability = Reliability::Z_RELIABILITY_BEST_EFFORT;
 #endif
@@ -320,6 +326,8 @@ class Session : public Owned<::z_owned_session_t> {
         /// @brief Whether Zenoh will NOT wait to batch this message with others to reduce the bandwith.
         bool is_express = false;
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief Allowed destination.
         Locality allowed_destination = ::zc_locality_default();
 #endif
@@ -328,10 +336,14 @@ class Session : public Owned<::z_owned_session_t> {
         /// @brief  An optional encoding of the message payload and/or attachment.
         std::optional<Encoding> encoding = {};
 #if defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The put operation reliability.
         Reliability reliability = Reliability::Z_RELIABILITY_BEST_EFFORT;
 #endif
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The source info of this message.
         std::optional<SourceInfo> source_info = {};
 #endif
@@ -529,10 +541,14 @@ class Session : public Owned<::z_owned_session_t> {
         /// @brief If true, Zenoh will not wait to batch this message with others to reduce the bandwith.
         bool is_express = false;
 #if defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief The publisher reliability.
         Reliability reliability = Reliability::Z_RELIABILITY_BEST_EFFORT;
 #endif
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+        /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+        /// release.
         /// @brief Allowed destination.
         Locality allowed_destination = ::zc_locality_default();
 #endif
@@ -574,6 +590,8 @@ class Session : public Owned<::z_owned_session_t> {
     }
 
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Fetches the Zenoh IDs of all connected routers.
     /// @param err if not null, the result code will be written to this location, otherwise ZException exception will be
     /// thrown in case of error.
@@ -674,6 +692,8 @@ class Session : public Owned<::z_owned_session_t> {
 #endif
 
 #if defined(ZENOHCXX_ZENOHC) && defined(UNSTABLE)
+    /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future
+    /// release.
     /// @brief Options to pass to ``Session::liveliness_declare_token``.
     struct LivelinessDeclarationOptions {
        protected:

include/zenoh/api/shm/buffer/zshm.hxx

@@ -22,6 +22,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief An immutable SHM buffer
 class ZShm : public Owned<::z_owned_shm_t> {
     friend class ZShmMut;

include/zenoh/api/shm/buffer/zshmmut.hxx

@@ -18,6 +18,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief A mutable SHM buffer
 class ZShmMut : public Owned<::z_owned_shm_mut_t> {
     friend class ZShm;

include/zenoh/api/shm/client/shm_client.hxx

@@ -22,6 +22,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief An interface for making custom SHM clients
 class CppShmClient {
    public:
@@ -46,6 +47,7 @@ inline void _z_cpp_shm_client_drop_fn(void* context) { delete static_cast<CppShm
 }
 }  // namespace shm::client::closures
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief An SHM client for reading shared memory buffers
 class ShmClient : public Owned<::z_owned_shm_client_t> {
     friend class ShmClientStorage;

include/zenoh/api/shm/client/shm_segment.hxx

@@ -16,6 +16,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief An interface for accessing custom SHM segments
 class CppShmSegment {
    public:

include/zenoh/api/shm/client_storage/client_storage.hxx

@@ -22,6 +22,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief A storage for SHM clients. Session constructed with instance of this type
 /// gets capabilities to read SHM buffers for Protocols added to this instance.
 class ShmClientStorage : public Owned<::z_owned_shm_client_storage_t> {

include/zenoh/api/shm/protocol_implementations/posix/posix_shm_client.hxx

@@ -17,6 +17,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief Client factory implementation for particular shared memory protocol
 class PosixShmClient : public ShmClient {
    public:

include/zenoh/api/shm/protocol_implementations/posix/posix_shm_provider.hxx

@@ -18,6 +18,7 @@
 
 namespace zenoh {
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief An SHM provider implementing zenoh-standard POSIX shared memory protocol
 class PosixShmProvider : public ShmProvider {
    public:

include/zenoh/api/shm/provider/alloc_layout.hxx

@@ -46,6 +46,7 @@ inline void _z_alloc_layout_async_interface_drop_fn(void* context) {
 }
 }  // namespace shm::provider::closures
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 class AllocLayout : public Owned<::z_owned_alloc_layout_t> {
    public:
     /// @name Constructors

include/zenoh/api/shm/provider/chunk.hxx

@@ -15,10 +15,12 @@
 
 namespace zenoh {
 
-/// A ChunkDescriptor
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief A ChunkDescriptor.
 typedef z_chunk_descriptor_t ChunkDescriptor;
 
-/// An AllocatedChunk
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief An AllocatedChunk.
 typedef z_allocated_chunk_t AllocatedChunk;
 
 }  // end of namespace zenoh

include/zenoh/api/shm/provider/shm_provider.hxx

@@ -104,6 +104,7 @@ class ShmProvider : public Owned<::z_owned_shm_provider_t> {
     }
 };
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 class CppShmProvider : public ShmProvider {
     friend class AllocLayout;
 

include/zenoh/api/shm/provider/types.hxx

@@ -21,26 +21,26 @@
 
 namespace zenoh {
 
-/**
- * Allocation errors
- *
- *     - **NEED_DEFRAGMENT**: defragmentation needed
- *     - **OUT_OF_MEMORY**: the provider is out of memory
- *     - **OTHER**: other error
- */
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief Allocation errors.
+///
+///    - **NEED_DEFRAGMENT**: defragmentation needed
+///    - **OUT_OF_MEMORY**: the provider is out of memory
+///    - **OTHER**: other error
 typedef ::z_alloc_error_t AllocError;
 
-/**
- * Layouting errors
- *
- * Z_LAYOUT_ERROR_INCORRECT_LAYOUT_ARGS: layout arguments are incorrect
- * Z_LAYOUT_ERROR_PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider
- */
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief Layouting errors.
+///
+/// * Z_LAYOUT_ERROR_INCORRECT_LAYOUT_ARGS: layout arguments are incorrect
+/// * Z_LAYOUT_ERROR_PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider
 typedef ::z_layout_error_t LayoutError;
 
-/// An AllocAlignment.
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief An AllocAlignment.
 typedef ::z_alloc_alignment_t AllocAlignment;
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 class MemoryLayout : public Owned<::z_owned_memory_layout_t> {
     friend class PosixShmProvider;
     MemoryLayout(zenoh::detail::null_object_t) : Owned(nullptr) {}
@@ -74,7 +74,8 @@ class MemoryLayout : public Owned<::z_owned_memory_layout_t> {
     }
 };
 
-/// SHM chunk allocation result
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief SHM chunk allocation result
 class ChunkAllocResult : public Owned<::z_owned_chunk_alloc_result_t> {
     friend class CppShmProviderBackend;
 
@@ -90,10 +91,12 @@ class ChunkAllocResult : public Owned<::z_owned_chunk_alloc_result_t> {
     ChunkAllocResult(AllocError error) : Owned(nullptr) { ::z_chunk_alloc_result_new_error(&this->_0, error); }
 };
 
-/// SHM buffer allocation result
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief SHM buffer allocation result
 typedef std::variant<ZShmMut, AllocError> BufAllocResult;
 
-/// SHM buffer layouting and allocation result
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief SHM buffer layouting and allocation result
 typedef std::variant<ZShmMut, AllocError, LayoutError> BufLayoutAllocResult;
 
 }  // end of namespace zenoh

include/zenoh/api/source_info.hxx

@@ -22,7 +22,8 @@
 
 namespace zenoh {
 #ifdef ZENOHCXX_ZENOHC
-/// The global unique id of a Zenoh entity.
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief The global unique id of a Zenoh entity.
 class EntityGlobalId : public Copyable<::z_entity_global_id_t> {
     using Copyable::Copyable;
     friend struct interop::detail::Converter;
@@ -37,6 +38,7 @@ class EntityGlobalId : public Copyable<::z_entity_global_id_t> {
     uint32_t eid() const { return ::z_entity_global_id_eid(&this->inner()); }
 };
 
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
 /// @brief Informations on the Zenoh source.
 class SourceInfo : public Owned<::z_owned_source_info_t> {
    public:

include/zenoh/api/timestamp.hxx

@@ -33,6 +33,8 @@ class Timestamp : public Copyable<::z_timestamp_t> {
     uint64_t get_time() const { return ::z_timestamp_ntp64_time(&this->inner()); }
 
 #if defined UNSTABLE
+    /// @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.
     Id get_id() const { return interop::into_copyable_cpp_obj<Id>(::z_timestamp_id(&this->inner())); }