Readme/docs update

README.md

@@ -192,24 +192,16 @@ See also `configure_include_project` function in [helpers.cmake] for more inform
 ./target/release/examples/z_pub_thr
 ```
 
-## API conventions
+## Documentation
+Zenoh-c API documentation is available on [Read the Docs](https://zenoh-c.readthedocs.io/en/latest/index.html).
 
-Most of the types exposed by the `zenoh-c` API are types for which destruction is necessary. To help you spot these types, we name them with the convention that any destructible type must start by `z_owned`.
+It can be built manually by performing the following steps:
 
-For maximum performance, we try to make as few copies as possible. Sometimes, this implies moving data that you `z_owned`. Any function that takes a non-const pointer to a `z_owned` type will perform its destruction. To make this pattern more obvious, we encourage you to use the `z_move` macro instead of a simple `&` to create these pointers. Rest assured that all `z_owned` types are double-free safe, and that you may check whether any `z_owned_X_t` typed value is still valid by using `z_X_check(&val)`, or the `z_check(val)` macro if you're using C11.
-
-We hope this convention will help you streamline your memory-safe usage of zenoh, as following it should make looking for leaks trivial: simply search for paths where a value of a `z_owned` type hasn't been passed to a function using `z_move`.
-
-Functions that simply need to borrow your data will instead take values of the associated `z_X_t` type. You may construct them using `z_X_loan(&val)` (or the `z_loan(val)` generic macro with C11).
-
-Note that some `z_X_t` typed values can be constructed without needing to `z_borrow` their owned variants. This allows you to reduce the amount of copies realized in your program.
-
-The examples have been written with C11 in mind, using the conventions we encourage you to follow.
-
-Finally, we strongly advise that you refrain from using structure field that starts with `_`:
-
-- We try to maintain a common API between `zenoh-c` and [`zenoh-pico`](https://github.com/eclipse-zenoh/zenoh-pico), such that porting code from one to the other is, ideally, trivial. However, some types must have distinct representations in either library, meaning that using these representations explicitly will get you in trouble when porting.
-- We reserve the right to change the memory layout of any type which has `_`-prefixed fields, so trying to use them might cause your code to break on updates.
+```bash
+cd docs
+doxygen
+sphinx-build -b html . _build/html
+```
 
 ## Cross-Compilation
 

docs/concepts.rst

@@ -151,8 +151,11 @@ Name Prefixes `z_`, `zc_`, `ze_`
 
 Most functions and types in the C API use the `z_` prefix, which applies to the common zenoh C API
 (currently Rust-based zenoh-c and pure C zenoh-pico).
+We try to maintain a common API between `zenoh-c` and `zenoh-pico`, such that porting code from one to the other is, ideally, trivial.
+However, due design limitations some functionality might be represented differently (or simply be not available) in either library.
+The `zc_` prefix is used for functions/structs specific to `zenoh-c`. `zenoh-pico` uses the `zp_` prefix for the same purpose.
 
-The `zc_` prefix is specific to zenoh-c. zenoh-pico uses the `zp_` prefix for the same purpose.
 
 The `ze_` prefix identifies functions and types from the `zenoh-ext` Rust library that are not
-part of the core Zenoh API and therefore are placed in a separate namespace.
+part of the core Zenoh API and therefore are placed in a separate namespace. Note, that this functionality might not
+be fully available in `zenoh-pico`.