From 0cddc67bdb60d252479baf7273d150539562546e Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Thu, 19 Feb 2026 13:54:28 -0500
Subject: [PATCH] Add doc-strs to `get_root()` + `maybe_open_portal()`

Brief descriptions for both fns in `._discovery` clarifying
what each delivers and under what conditions.

(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 tractor/_discovery.py | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/tractor/_discovery.py b/tractor/_discovery.py
index edc43d86..bf4d066a 100644
--- a/tractor/_discovery.py
+++ b/tractor/_discovery.py
@@ -91,10 +91,13 @@ async def get_registry(
 
 
 @acm
-async def get_root(
-    **kwargs,
-) -> AsyncGenerator[Portal, None]:
+async def get_root(**kwargs) -> AsyncGenerator[Portal, None]:
+    '''
+    Deliver the current actor's "root process" actor (yes in actor
+    and proc tree terms) by delivering a `Portal` from the spawn-time
+    provided contact address.
 
+    '''
     # TODO: rename mailbox to `_root_maddr` when we finally
     # add and impl libp2p multi-addrs?
     addr = _runtime_vars['_root_mailbox']
@@ -193,6 +196,11 @@ async def maybe_open_portal(
     addr: UnwrappedAddress,
     name: str,
 ):
+    '''
+    Open a `Portal` to the actor serving @ `addr` or `None` if no
+    peer can be contacted or found.
+
+    '''
     async with query_actor(
         name=name,
         regaddr=addr,