[incubator-ponymail-foal] 01/02: Docco

[se...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sebb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-ponymail-foal.git

commit 80e7beceae22fbdd331f8844669acdac2d535802
Author: Sebb <se...@apache.org>
AuthorDate: Tue Dec 28 15:31:27 2021 +0000

    Docco
---
 server/plugins/messages.py | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/server/plugins/messages.py b/server/plugins/messages.py
index 075cf22..bbce740 100644
--- a/server/plugins/messages.py
+++ b/server/plugins/messages.py
@@ -273,8 +273,11 @@ async def get_email_irt(
     irt: str,
 ) -> typing.List[dict]:
     """
-    Returns a list of mbox document(s) that are related. May be empty.
-    The calling code is responsible for checking if entries are accessible
+    Returns a list of mbox document(s) that are related,
+    i.e. where the parameter matches 'in-reply-to' or 'references'
+    May be empty.
+    Docs have been checked for accessibility.
+    Caller must check if the doc is "deleted"
     """
     assert session.database, DATABASE_NOT_CONNECTED
     doctype = session.database.dbs.db_mbox
@@ -300,6 +303,12 @@ async def get_email_irt(
 
 
 async def get_source(session: plugins.session.SessionObject, permalink: str = None, raw=False):
+    """
+        Get the source document for an email, or None if it does not find exactly one match.
+        If the source cannot be found using the id, it checks for a match by Permalink.
+
+        The caller must check if access is allowed.
+    """
     assert session.database, DATABASE_NOT_CONNECTED
     doctype = session.database.dbs.db_source
     try: