feat(queue): update docs

apps/emqx_ds_shared_sub/README.md

@@ -13,7 +13,6 @@ On the code level, the application is organized in the following way:
 * The nesting reflects nesting/ownership of entity states.
 * The bold arrow represent the [most complex interaction](https://github.com/emqx/eip/blob/main/active/0028-durable-shared-subscriptions.md#shared-subscription-session-handler), between session-side group subscription state machine (**GroupSM**) and the shared subscription leader (**Leader**).
 
-
 # Contributing
 
 Please see our [contributing.md](../../CONTRIBUTING.md).

apps/emqx_ds_shared_sub/src/emqx_ds_shared_sub_agent.erl

@@ -54,14 +54,23 @@
     session_id := emqx_persistent_session_ds:id()
 }.
 
-%% Techinically, group_id and share_topic_filter are the same.
+%% We speak in the terms of share_topic_filter in the module API
-%% However, we speak in the terms of share_topic_filter in the API,
+%% which is consumed by persistent session.
-%% which is known to the shared subscription handler of persistent session.
 %%
-%% And we speak in the terms of group_id internally:
+%% We speak in the terms of group_id internally:
-%% * we keep group_sm's in the state by group_id
+%% * to identfy shared subscription's group_sm in the state;
-%% * we use group_id to address group_sm's, e.g. when sending messages to them
+%% * to addres agent's group_sm while communicating with leader.
-%% from leader or from themselves.
+%% * to identify the leader itself.
+%%
+%% share_topic_filter should be uniquely determined by group_id. See MQTT 5.0 spec:
+%%
+%% > Note that "$share/consumer1//finance" and "$share/consumer1/sport/tennis/+"
+%% > are distinct shared subscriptions, even though they have the same ShareName.
+%% > While they might be related in some way, no specific relationship between them
+%% > is implied by them having the same ShareName.
+%%
+%% So we just use the full share_topic_filter record as group_id.
+
 -define(group_id(ShareTopicFilter), ShareTopicFilter).
 -define(share_topic_filter(GroupId), GroupId).