From fcbceb07ae9bd4160a294ab5c982b6882eca6a7b Mon Sep 17 00:00:00 2001
From: Luca Cominardi <luca.cominardi@gmail.com>
Date: Tue, 12 Mar 2024 12:43:21 +0100
Subject: [PATCH] Improve Endpoint and Locator doc

---
 commons/zenoh-protocol/src/core/endpoint.rs | 7 ++++++-
 commons/zenoh-protocol/src/core/locator.rs  | 6 +++---
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/commons/zenoh-protocol/src/core/endpoint.rs b/commons/zenoh-protocol/src/core/endpoint.rs
index 5e921345e4..a8fcb3ae98 100644
--- a/commons/zenoh-protocol/src/core/endpoint.rs
+++ b/commons/zenoh-protocol/src/core/endpoint.rs
@@ -497,7 +497,12 @@ impl fmt::Debug for ConfigMut<'_> {
     }
 }
 
-/// A `String` that respects the [`EndPoint`] canon form: `<locator>#<config>`, such that `<locator>` is a valid [`Locator`] `<config>` is of the form `<key1>=<value1>;...;<keyN>=<valueN>` where keys are alphabetically sorted.
+/// A string that respects the [`EndPoint`] canon form: `<locator>[#<config>]`.
+///
+/// `<locator>` is a valid [`Locator`] and `<config>` is of the form `<key1>=<value1>;...;<keyN>=<valueN>` where keys are alphabetically sorted.
+/// `<config>` is optional and can be provided to configure some aspectes for an [`EndPoint`], e.g. the interface to listen on or connect to.
+///
+/// A full [`EndPoint`] string is hence in the form of `<proto>/<address>[?<metadata>][#config]`.
 #[derive(Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
 #[serde(into = "String")]
 #[serde(try_from = "String")]
diff --git a/commons/zenoh-protocol/src/core/locator.rs b/commons/zenoh-protocol/src/core/locator.rs
index 42379f2b65..50b909b12f 100644
--- a/commons/zenoh-protocol/src/core/locator.rs
+++ b/commons/zenoh-protocol/src/core/locator.rs
@@ -16,9 +16,9 @@ use alloc::{borrow::ToOwned, string::String};
 use core::{convert::TryFrom, fmt, hash::Hash, str::FromStr};
 use zenoh_result::{Error as ZError, ZResult};
 
-// Locator
-/// A `String` that respects the [`Locator`] canon form: `<proto>/<address>[?<metadata>]`,
-/// such that `<metadata>` is of the form `<key1>=<value1>;...;<keyN>=<valueN>` where keys are alphabetically sorted.
+/// A string that respects the [`Locator`] canon form: `<proto>/<address>[?<metadata>]`.
+///
+/// `<metadata>` is of the form `<key1>=<value1>;...;<keyN>=<valueN>` where keys are alphabetically sorted.
 #[derive(Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
 #[serde(into = "String")]
 #[serde(try_from = "String")]