bgpd,lib: document the table id / instance usage

Document where relevant about the instance overload to table ID so users
know what to expect.

Signed-off-by: Rafael Zalamena <rzalamena@opensourcerouting.org>

2 files changed, 16 insertions, 0 deletions

diff --git a/lib/zclient.c b/lib/zclient.c
index 8fc9addf2f..9f6542eb31 100644
--- a/lib/zclient.c
+++ b/lib/zclient.c
@@ -4774,6 +4774,16 @@ static void zclient_redistribute_table_direct(struct zclient *zclient, vrf_id_t
 void zclient_redistribute(int command, struct zclient *zclient, afi_t afi,
 			  int type, unsigned short instance, vrf_id_t vrf_id)
 {
+	/*
+	 * When asking for table-direct redistribution the parameter
+	 * `instance` has a different meaning: it means table
+	 * identification.
+	 *
+	 * The table identification information is stored in
+	 * `zclient->mi_redist` along with the VRF identification
+	 * information in a pair (different from the usual single protocol
+	 * instance value).
+	 */
 	if (type == ZEBRA_ROUTE_TABLE_DIRECT) {
 		zclient_redistribute_table_direct(zclient, vrf_id, afi, instance, command);
 		return;
diff --git a/lib/zclient.h b/lib/zclient.h
index 35e23ddf63..f3657822b8 100644
--- a/lib/zclient.h
+++ b/lib/zclient.h
@@ -271,6 +271,12 @@ struct redist_proto {
 /**
  * Redistribute table direct instance data structure: keeps the VRF
  * that subscribed to the table ID.
+ *
+ * **NOTE**
+ * `table_id` is an integer because that is what the netlink interface
+ * uses for route attribute RTA_TABLE (32bit int), however the whole
+ * zclient API uses `unsigned short` (and CLI commands) so it will be
+ * limited to the range 1 to 65535.
  */
 struct redist_table_direct {
 	vrf_id_t vrf_id;