From 4b0ca40b179f1249527f34453bf00f4c6a83e95b Mon Sep 17 00:00:00 2001
From: Tyler Goodlet <jgbt@protonmail.com>
Date: Mon, 11 Apr 2022 08:48:17 -0400
Subject: [PATCH] Document "fqsn" on `Symbol` method

---
 piker/data/_source.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/piker/data/_source.py b/piker/data/_source.py
index 9c760bc6..3fa6db7b 100644
--- a/piker/data/_source.py
+++ b/piker/data/_source.py
@@ -222,6 +222,23 @@ class Symbol(BaseModel):
             return (key, broker)
 
     def front_fqsn(self) -> str:
+        '''
+        fqsn = "fully qualified symbol name"
+
+        Basically the idea here is for all client-ish code (aka programs/actors
+        that ask the provider agnostic layers in the stack for data) should be
+        able to tell which backend / venue / derivative each data feed/flow is
+        from by an explicit string key of the current form:
+
+        <instrumentname>.<venue>.<suffixwithmetadata>.<brokerbackendname>
+
+        TODO: I have thoughts that we should actually change this to be
+        more like an "attr lookup" (like how the web should have done
+        urls, but marketting peeps ruined it etc. etc.):
+
+        <broker>.<venue>.<instrumentname>.<suffixwithmetadata>
+
+        '''
         tokens = self.tokens()
         fqsn = '.'.join(tokens)
         return fqsn