From 896ae4b589cf62e0ea1241a753c5635eafcc3f90 Mon Sep 17 00:00:00 2001 From: Denis Biryukov Date: Tue, 10 Sep 2024 16:43:29 +0200 Subject: [PATCH] mark unstable features in the docs --- include/zenoh/api/enums.hxx | 3 +- include/zenoh/api/hello.hxx | 2 + include/zenoh/api/id.hxx | 2 + include/zenoh/api/keyexpr.hxx | 5 ++- include/zenoh/api/liveliness.hxx | 3 +- include/zenoh/api/publisher.hxx | 4 ++ include/zenoh/api/query.hxx | 4 ++ include/zenoh/api/reply.hxx | 2 + include/zenoh/api/sample.hxx | 4 ++ include/zenoh/api/session.hxx | 20 ++++++++++ include/zenoh/api/shm/buffer/zshm.hxx | 1 + include/zenoh/api/shm/buffer/zshmmut.hxx | 1 + include/zenoh/api/shm/client/shm_client.hxx | 2 + include/zenoh/api/shm/client/shm_segment.hxx | 1 + .../api/shm/client_storage/client_storage.hxx | 1 + .../posix/posix_shm_client.hxx | 1 + .../posix/posix_shm_provider.hxx | 1 + .../zenoh/api/shm/provider/alloc_layout.hxx | 1 + include/zenoh/api/shm/provider/chunk.hxx | 6 ++- .../zenoh/api/shm/provider/shm_provider.hxx | 1 + include/zenoh/api/shm/provider/types.hxx | 37 ++++++++++--------- include/zenoh/api/source_info.hxx | 4 +- include/zenoh/api/timestamp.hxx | 2 + 23 files changed, 84 insertions(+), 24 deletions(-) diff --git a/include/zenoh/api/enums.hxx b/include/zenoh/api/enums.hxx index 2086b542..2411027a 100644 --- a/include/zenoh/api/enums.hxx +++ b/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. diff --git a/include/zenoh/api/hello.hxx b/include/zenoh/api/hello.hxx index e247b649..e1dc1ba2 100644 --- a/include/zenoh/api/hello.hxx +++ b/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(::z_hello_zid(interop::as_loaned_c_ptr(*this))); }; diff --git a/include/zenoh/api/id.hxx b/include/zenoh/api/id.hxx index 59c3e4b5..08b8be23 100644 --- a/include/zenoh/api/id.hxx +++ b/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& bytes() const { return *reinterpret_cast*>(&_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(&id)->id; diff --git a/include/zenoh/api/keyexpr.hxx b/include/zenoh/api/keyexpr.hxx index 8f90d527..c23aff58 100644 --- a/include/zenoh/api/keyexpr.hxx +++ b/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. diff --git a/include/zenoh/api/liveliness.hxx b/include/zenoh/api/liveliness.hxx index b8a5fa16..587b6dac 100644 --- a/include/zenoh/api/liveliness.hxx +++ b/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. diff --git a/include/zenoh/api/publisher.hxx b/include/zenoh/api/publisher.hxx index cb812122..daea66f6 100644 --- a/include/zenoh/api/publisher.hxx +++ b/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 = {}; #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 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 { diff --git a/include/zenoh/api/query.hxx b/include/zenoh/api/query.hxx index 52f9e1ba..8edbee35 100644 --- a/include/zenoh/api/query.hxx +++ b/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 = {}; #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 source_info = {}; #endif @@ -171,6 +173,8 @@ class Query : public Owned<::z_owned_query_t> { /// @brief the timestamp of this message. std::optional 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 source_info = {}; #endif diff --git a/include/zenoh/api/reply.hxx b/include/zenoh/api/reply.hxx index dece2865..1a4f7991 100644 --- a/include/zenoh/api/reply.hxx +++ b/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 get_replier_id() const { diff --git a/include/zenoh/api/sample.hxx b/include/zenoh/api/sample.hxx index 76362fa4..b1ac325c 100644 --- a/include/zenoh/api/sample.hxx +++ b/include/zenoh/api/sample.hxx @@ -91,6 +91,8 @@ 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(::z_sample_source_info(interop::as_loaned_c_ptr(*this))); @@ -98,6 +100,8 @@ class Sample : public Owned<::z_owned_sample_t> { #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)); } diff --git a/include/zenoh/api/session.hxx b/include/zenoh/api/session.hxx index c5148f7f..3d1d2b57 100644 --- a/include/zenoh/api/session.hxx +++ b/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(::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 = {}; #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 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 = {}; #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 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: diff --git a/include/zenoh/api/shm/buffer/zshm.hxx b/include/zenoh/api/shm/buffer/zshm.hxx index e6a0d5ed..c2ec37ef 100644 --- a/include/zenoh/api/shm/buffer/zshm.hxx +++ b/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; diff --git a/include/zenoh/api/shm/buffer/zshmmut.hxx b/include/zenoh/api/shm/buffer/zshmmut.hxx index e7cb8d5d..4fc18a28 100644 --- a/include/zenoh/api/shm/buffer/zshmmut.hxx +++ b/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; diff --git a/include/zenoh/api/shm/client/shm_client.hxx b/include/zenoh/api/shm/client/shm_client.hxx index 8c182b0e..e691f0bf 100644 --- a/include/zenoh/api/shm/client/shm_client.hxx +++ b/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 { friend class ShmClientStorage; diff --git a/include/zenoh/api/shm/client/shm_segment.hxx b/include/zenoh/api/shm/client/shm_segment.hxx index 9030b04d..0bf84184 100644 --- a/include/zenoh/api/shm/client/shm_segment.hxx +++ b/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: diff --git a/include/zenoh/api/shm/client_storage/client_storage.hxx b/include/zenoh/api/shm/client_storage/client_storage.hxx index a152f08b..106ddc31 100644 --- a/include/zenoh/api/shm/client_storage/client_storage.hxx +++ b/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> { diff --git a/include/zenoh/api/shm/protocol_implementations/posix/posix_shm_client.hxx b/include/zenoh/api/shm/protocol_implementations/posix/posix_shm_client.hxx index 2d62ba2b..9441b110 100644 --- a/include/zenoh/api/shm/protocol_implementations/posix/posix_shm_client.hxx +++ b/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: diff --git a/include/zenoh/api/shm/protocol_implementations/posix/posix_shm_provider.hxx b/include/zenoh/api/shm/protocol_implementations/posix/posix_shm_provider.hxx index 6599cc83..2e8401bd 100644 --- a/include/zenoh/api/shm/protocol_implementations/posix/posix_shm_provider.hxx +++ b/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: diff --git a/include/zenoh/api/shm/provider/alloc_layout.hxx b/include/zenoh/api/shm/provider/alloc_layout.hxx index 730d4ed9..8b84ea13 100644 --- a/include/zenoh/api/shm/provider/alloc_layout.hxx +++ b/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 diff --git a/include/zenoh/api/shm/provider/chunk.hxx b/include/zenoh/api/shm/provider/chunk.hxx index 4c55dfe8..fe390b57 100644 --- a/include/zenoh/api/shm/provider/chunk.hxx +++ b/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 diff --git a/include/zenoh/api/shm/provider/shm_provider.hxx b/include/zenoh/api/shm/provider/shm_provider.hxx index 325499c9..19b73d24 100644 --- a/include/zenoh/api/shm/provider/shm_provider.hxx +++ b/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; diff --git a/include/zenoh/api/shm/provider/types.hxx b/include/zenoh/api/shm/provider/types.hxx index 89db6509..5f2a7592 100644 --- a/include/zenoh/api/shm/provider/types.hxx +++ b/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 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 BufLayoutAllocResult; } // end of namespace zenoh diff --git a/include/zenoh/api/source_info.hxx b/include/zenoh/api/source_info.hxx index 2dbfef1d..ec5a69c7 100644 --- a/include/zenoh/api/source_info.hxx +++ b/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: diff --git a/include/zenoh/api/timestamp.hxx b/include/zenoh/api/timestamp.hxx index d79c3ede..ad7b1277 100644 --- a/include/zenoh/api/timestamp.hxx +++ b/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(::z_timestamp_id(&this->inner())); }