From 9c29166cfd405a8a52a0635326127ae80ccfdd9e Mon Sep 17 00:00:00 2001
From: Jean-Roland <jean.roland.gosse@gmail.com>
Date: Fri, 11 Oct 2024 09:25:49 +0200
Subject: [PATCH] doc: add warning on null functions

---
 include/zenoh-pico/collections/bytes.h               |  3 ++-
 include/zenoh-pico/collections/slice.h               |  1 +
 include/zenoh-pico/collections/string.h              |  1 +
 include/zenoh-pico/net/encoding.h                    |  2 ++
 include/zenoh-pico/net/publish.h                     |  5 +++--
 include/zenoh-pico/net/query.h                       |  6 ++++--
 include/zenoh-pico/net/reply.h                       |  4 +++-
 include/zenoh-pico/net/sample.h                      |  1 +
 include/zenoh-pico/net/subscribe.h                   |  6 +++---
 include/zenoh-pico/protocol/core.h                   | 12 +++++++++---
 .../zenoh-pico/protocol/definitions/declarations.h   |  9 +++++++++
 include/zenoh-pico/protocol/definitions/interest.h   |  3 ++-
 include/zenoh-pico/protocol/definitions/network.h    |  1 +
 include/zenoh-pico/protocol/keyexpr.h                |  1 +
 14 files changed, 42 insertions(+), 13 deletions(-)

diff --git a/include/zenoh-pico/collections/bytes.h b/include/zenoh-pico/collections/bytes.h
index 12430bdfc..2496520c1 100644
--- a/include/zenoh-pico/collections/bytes.h
+++ b/include/zenoh-pico/collections/bytes.h
@@ -45,8 +45,9 @@ typedef struct {
     _z_arc_slice_svec_t _slices;
 } _z_bytes_t;
 
-bool _z_bytes_check(const _z_bytes_t *bytes);
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_bytes_t _z_bytes_null(void) { return (_z_bytes_t){0}; }
+bool _z_bytes_check(const _z_bytes_t *bytes);
 z_result_t _z_bytes_append_bytes(_z_bytes_t *dst, _z_bytes_t *src);
 z_result_t _z_bytes_append_slice(_z_bytes_t *dst, _z_arc_slice_t *s);
 z_result_t _z_bytes_copy(_z_bytes_t *dst, const _z_bytes_t *src);
diff --git a/include/zenoh-pico/collections/slice.h b/include/zenoh-pico/collections/slice.h
index 7739dbc2e..b6b6f45a5 100644
--- a/include/zenoh-pico/collections/slice.h
+++ b/include/zenoh-pico/collections/slice.h
@@ -26,6 +26,7 @@ typedef struct {
     void *context;
 } _z_delete_context_t;
 
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_delete_context_t _z_delete_context_null(void) { return (_z_delete_context_t){0}; }
 
 static inline _z_delete_context_t _z_delete_context_create(void (*deleter)(void *context, void *data), void *context) {
diff --git a/include/zenoh-pico/collections/string.h b/include/zenoh-pico/collections/string.h
index 38af1a248..167604774 100644
--- a/include/zenoh-pico/collections/string.h
+++ b/include/zenoh-pico/collections/string.h
@@ -66,6 +66,7 @@ typedef struct {
     _z_slice_t _slice;
 } _z_string_t;
 
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_string_t _z_string_null(void) { return (_z_string_t){0}; }
 static inline bool _z_string_check(const _z_string_t *value) { return !_z_slice_is_empty(&value->_slice); }
 static inline _z_string_t _z_string_alias(const _z_string_t str) {
diff --git a/include/zenoh-pico/net/encoding.h b/include/zenoh-pico/net/encoding.h
index 959a15ddc..969f0c34e 100644
--- a/include/zenoh-pico/net/encoding.h
+++ b/include/zenoh-pico/net/encoding.h
@@ -26,6 +26,8 @@ typedef struct _z_encoding_t {
     _z_string_t schema;
     uint16_t id;
 } _z_encoding_t;
+
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_encoding_t _z_encoding_null(void) { return (_z_encoding_t){0}; }
 static inline bool _z_encoding_check(const _z_encoding_t *encoding) {
     return ((encoding->id != _Z_ENCODING_ID_DEFAULT) || _z_string_check(&encoding->schema));
diff --git a/include/zenoh-pico/net/publish.h b/include/zenoh-pico/net/publish.h
index e8e747429..b3bc40891 100644
--- a/include/zenoh-pico/net/publish.h
+++ b/include/zenoh-pico/net/publish.h
@@ -37,10 +37,11 @@ typedef struct _z_publisher_t {
 } _z_publisher_t;
 
 #if Z_FEATURE_PUBLICATION == 1
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
+static inline _z_publisher_t _z_publisher_null(void) { return (_z_publisher_t){0}; }
+static inline bool _z_publisher_check(const _z_publisher_t *publisher) { return !_Z_RC_IS_NULL(&publisher->_zn); }
 void _z_publisher_clear(_z_publisher_t *pub);
 void _z_publisher_free(_z_publisher_t **pub);
-static inline bool _z_publisher_check(const _z_publisher_t *publisher) { return !_Z_RC_IS_NULL(&publisher->_zn); }
-static inline _z_publisher_t _z_publisher_null(void) { return (_z_publisher_t){0}; }
 #endif
 
 #endif /* INCLUDE_ZENOH_PICO_NET_PUBLISH_H */
diff --git a/include/zenoh-pico/net/query.h b/include/zenoh-pico/net/query.h
index 38d9c2a60..703688a65 100644
--- a/include/zenoh-pico/net/query.h
+++ b/include/zenoh-pico/net/query.h
@@ -34,6 +34,7 @@ typedef struct _z_query_t {
     bool _anyke;
 } _z_query_t;
 
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_query_t _z_query_null(void) { return (_z_query_t){0}; }
 void _z_query_clear(_z_query_t *q);
 z_result_t _z_query_copy(_z_query_t *dst, const _z_query_t *src);
@@ -50,12 +51,13 @@ typedef struct {
 } _z_queryable_t;
 
 #if Z_FEATURE_QUERYABLE == 1
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
+static inline _z_queryable_t _z_queryable_null(void) { return (_z_queryable_t){0}; }
+static inline bool _z_queryable_check(const _z_queryable_t *queryable) { return !_Z_RC_IS_NULL(&queryable->_zn); }
 _z_query_t _z_query_create(_z_value_t *value, _z_keyexpr_t *key, const _z_slice_t *parameters, _z_session_rc_t *zn,
                            uint32_t request_id, const _z_bytes_t attachment);
 void _z_queryable_clear(_z_queryable_t *qbl);
 void _z_queryable_free(_z_queryable_t **qbl);
-static inline _z_queryable_t _z_queryable_null(void) { return (_z_queryable_t){0}; }
-static inline bool _z_queryable_check(const _z_queryable_t *queryable) { return !_Z_RC_IS_NULL(&queryable->_zn); }
 
 #endif
 
diff --git a/include/zenoh-pico/net/reply.h b/include/zenoh-pico/net/reply.h
index fde04f9ad..3a47c9199 100644
--- a/include/zenoh-pico/net/reply.h
+++ b/include/zenoh-pico/net/reply.h
@@ -57,6 +57,7 @@ typedef struct _z_reply_data_t {
     _z_reply_tag_t _tag;
 } _z_reply_data_t;
 
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_reply_data_t _z_reply_data_null(void) { return (_z_reply_data_t){0}; }
 void _z_reply_data_clear(_z_reply_data_t *rd);
 z_result_t _z_reply_data_copy(_z_reply_data_t *dst, const _z_reply_data_t *src);
@@ -77,8 +78,9 @@ typedef struct _z_reply_t {
     _z_reply_data_t data;
 } _z_reply_t;
 
-_z_reply_t _z_reply_move(_z_reply_t *src_reply);
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_reply_t _z_reply_null(void) { return (_z_reply_t){0}; }
+_z_reply_t _z_reply_move(_z_reply_t *src_reply);
 void _z_reply_clear(_z_reply_t *src);
 void _z_reply_free(_z_reply_t **hello);
 z_result_t _z_reply_copy(_z_reply_t *dst, const _z_reply_t *src);
diff --git a/include/zenoh-pico/net/sample.h b/include/zenoh-pico/net/sample.h
index 964967294..213e1eaa1 100644
--- a/include/zenoh-pico/net/sample.h
+++ b/include/zenoh-pico/net/sample.h
@@ -40,6 +40,7 @@ typedef struct _z_sample_t {
 } _z_sample_t;
 void _z_sample_clear(_z_sample_t *sample);
 
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_sample_t _z_sample_null(void) { return (_z_sample_t){0}; }
 static inline bool _z_sample_check(const _z_sample_t *sample) {
     return _z_keyexpr_check(&sample->keyexpr) || _z_encoding_check(&sample->encoding) ||
diff --git a/include/zenoh-pico/net/subscribe.h b/include/zenoh-pico/net/subscribe.h
index bbfbd0345..b8129673e 100644
--- a/include/zenoh-pico/net/subscribe.h
+++ b/include/zenoh-pico/net/subscribe.h
@@ -29,11 +29,11 @@ typedef struct {
 } _z_subscriber_t;
 
 #if Z_FEATURE_SUBSCRIPTION == 1
-
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
+static inline _z_subscriber_t _z_subscriber_null(void) { return (_z_subscriber_t){0}; }
+static inline bool _z_subscriber_check(const _z_subscriber_t *subscriber) { return !_Z_RC_IS_NULL(&subscriber->_zn); }
 void _z_subscriber_clear(_z_subscriber_t *sub);
 void _z_subscriber_free(_z_subscriber_t **sub);
-static inline bool _z_subscriber_check(const _z_subscriber_t *subscriber) { return !_Z_RC_IS_NULL(&subscriber->_zn); }
-static inline _z_subscriber_t _z_subscriber_null(void) { return (_z_subscriber_t){0}; }
 
 #endif
 
diff --git a/include/zenoh-pico/protocol/core.h b/include/zenoh-pico/protocol/core.h
index 986a4262f..d5f85299a 100644
--- a/include/zenoh-pico/protocol/core.h
+++ b/include/zenoh-pico/protocol/core.h
@@ -66,8 +66,9 @@ typedef struct {
     uint64_t time;
 } _z_timestamp_t;
 
-_z_timestamp_t _z_timestamp_duplicate(const _z_timestamp_t *tstamp);
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_timestamp_t _z_timestamp_null(void) { return (_z_timestamp_t){0}; }
+_z_timestamp_t _z_timestamp_duplicate(const _z_timestamp_t *tstamp);
 void _z_timestamp_clear(_z_timestamp_t *tstamp);
 bool _z_timestamp_check(const _z_timestamp_t *stamp);
 uint64_t _z_timestamp_ntp64_from_time(uint32_t seconds, uint32_t nanos);
@@ -163,8 +164,9 @@ typedef struct {
     _z_bytes_t payload;
     _z_encoding_t encoding;
 } _z_value_t;
-static inline _z_value_t _z_value_null(void) { return (_z_value_t){0}; }
 
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
+static inline _z_value_t _z_value_null(void) { return (_z_value_t){0}; }
 _z_value_t _z_value_steal(_z_value_t *value);
 z_result_t _z_value_copy(_z_value_t *dst, const _z_value_t *src);
 void _z_value_move(_z_value_t *dst, _z_value_t *src);
@@ -185,10 +187,12 @@ typedef struct {
     z_whatami_t _whatami;
     uint8_t _version;
 } _z_hello_t;
+
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
+static inline _z_hello_t _z_hello_null(void) { return (_z_hello_t){0}; }
 void _z_hello_clear(_z_hello_t *src);
 void _z_hello_free(_z_hello_t **hello);
 z_result_t _z_hello_copy(_z_hello_t *dst, const _z_hello_t *src);
-static inline _z_hello_t _z_hello_null(void) { return (_z_hello_t){0}; }
 
 bool _z_hello_check(const _z_hello_t *hello);
 
@@ -204,6 +208,8 @@ typedef struct {
     uint32_t _entity_id;
     uint32_t _source_sn;
 } _z_source_info_t;
+
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_source_info_t _z_source_info_null(void) { return (_z_source_info_t){0}; }
 
 typedef struct {
diff --git a/include/zenoh-pico/protocol/definitions/declarations.h b/include/zenoh-pico/protocol/definitions/declarations.h
index 5c893360f..cb8224239 100644
--- a/include/zenoh-pico/protocol/definitions/declarations.h
+++ b/include/zenoh-pico/protocol/definitions/declarations.h
@@ -24,21 +24,25 @@ typedef struct {
     uint16_t _id;
     _z_keyexpr_t _keyexpr;
 } _z_decl_kexpr_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_decl_kexpr_t _z_decl_kexpr_null(void) { return (_z_decl_kexpr_t){0}; }
 typedef struct {
     uint16_t _id;
 } _z_undecl_kexpr_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_undecl_kexpr_t _z_undecl_kexpr_null(void) { return (_z_undecl_kexpr_t){0}; }
 
 typedef struct {
     _z_keyexpr_t _keyexpr;
     uint32_t _id;
 } _z_decl_subscriber_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_decl_subscriber_t _z_decl_subscriber_null(void) { return (_z_decl_subscriber_t){0}; }
 typedef struct {
     uint32_t _id;
     _z_keyexpr_t _ext_keyexpr;
 } _z_undecl_subscriber_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_undecl_subscriber_t _z_undecl_subscriber_null(void) { return (_z_undecl_subscriber_t){0}; }
 
 typedef struct {
@@ -49,27 +53,32 @@ typedef struct {
         uint16_t _distance;
     } _ext_queryable_info;
 } _z_decl_queryable_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_decl_queryable_t _z_decl_queryable_null(void) { return (_z_decl_queryable_t){0}; }
 typedef struct {
     uint32_t _id;
     _z_keyexpr_t _ext_keyexpr;
 } _z_undecl_queryable_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_undecl_queryable_t _z_undecl_queryable_null(void) { return (_z_undecl_queryable_t){0}; }
 
 typedef struct {
     _z_keyexpr_t _keyexpr;
     uint32_t _id;
 } _z_decl_token_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_decl_token_t _z_decl_token_null(void) { return (_z_decl_token_t){0}; }
 typedef struct {
     uint32_t _id;
     _z_keyexpr_t _ext_keyexpr;
 } _z_undecl_token_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_undecl_token_t _z_undecl_token_null(void) { return (_z_undecl_token_t){0}; }
 
 typedef struct {
     bool _placeholder;  // In case we add extensions
 } _z_decl_final_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_decl_final_t _z_decl_final_null(void) { return (_z_decl_final_t){0}; }
 
 typedef struct {
diff --git a/include/zenoh-pico/protocol/definitions/interest.h b/include/zenoh-pico/protocol/definitions/interest.h
index bc0fda4df..8479f090f 100644
--- a/include/zenoh-pico/protocol/definitions/interest.h
+++ b/include/zenoh-pico/protocol/definitions/interest.h
@@ -36,9 +36,10 @@ typedef struct {
     uint32_t _id;
     uint8_t flags;
 } _z_interest_t;
+
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_interest_t _z_interest_null(void) { return (_z_interest_t){0}; }
 void _z_interest_clear(_z_interest_t* decl);
-
 _z_interest_t _z_make_interest(_Z_MOVE(_z_keyexpr_t) key, uint32_t id, uint8_t flags);
 _z_interest_t _z_make_interest_final(uint32_t id);
 
diff --git a/include/zenoh-pico/protocol/definitions/network.h b/include/zenoh-pico/protocol/definitions/network.h
index fa2f057f0..476831765 100644
--- a/include/zenoh-pico/protocol/definitions/network.h
+++ b/include/zenoh-pico/protocol/definitions/network.h
@@ -149,6 +149,7 @@ _z_n_msg_request_exts_t _z_n_msg_request_needed_exts(const _z_n_msg_request_t *m
 void _z_n_msg_request_clear(_z_n_msg_request_t *msg);
 
 typedef _z_reply_body_t _z_push_body_t;
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_push_body_t _z_push_body_null(void) { return (_z_push_body_t){0}; }
 
 _z_push_body_t _z_push_body_steal(_z_push_body_t *msg);
diff --git a/include/zenoh-pico/protocol/keyexpr.h b/include/zenoh-pico/protocol/keyexpr.h
index fb8330717..61a16e634 100644
--- a/include/zenoh-pico/protocol/keyexpr.h
+++ b/include/zenoh-pico/protocol/keyexpr.h
@@ -26,6 +26,7 @@ bool _z_keyexpr_suffix_intersects(const _z_keyexpr_t *left, const _z_keyexpr_t *
 bool _z_keyexpr_suffix_equals(const _z_keyexpr_t *left, const _z_keyexpr_t *right);
 
 /*------------------ clone/Copy/Free helpers ------------------*/
+// Warning: None of the sub-types require a non-0 initialization. Add a init function if it changes.
 static inline _z_keyexpr_t _z_keyexpr_null(void) { return (_z_keyexpr_t){0}; }
 static inline _z_keyexpr_t _z_keyexpr_alias(const _z_keyexpr_t src) {
     return (_z_keyexpr_t){