From 1b8127eea13b7d1e4e86d050767a56487ad7a505 Mon Sep 17 00:00:00 2001
From: dece <shgck@pistache.land>
Date: Thu, 11 Mar 2021 19:16:15 +0100
Subject: [PATCH] add module docstrings

---
 bebop/browser.py      |  2 ++
 bebop/colors.py       |  2 ++
 bebop/command_line.py |  1 +
 bebop/gemtext.py      |  7 +++++++
 bebop/history.py      |  3 +++
 bebop/mouse.py        |  2 ++
 bebop/navigation.py   |  4 +++-
 bebop/page.py         |  2 ++
 bebop/protocol.py     | 14 +++++++++++++-
 bebop/rendering.py    |  7 +++++++
 bebop/tofu.py         |  6 ++++++
 11 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/bebop/browser.py b/bebop/browser.py
index 72ccb78..4c732b9 100644
--- a/bebop/browser.py
+++ b/bebop/browser.py
@@ -1,3 +1,5 @@
+"""Main browser logic."""
+
 import curses
 import curses.ascii
 import curses.textpad
diff --git a/bebop/colors.py b/bebop/colors.py
index 9cd8aab..37095ec 100644
--- a/bebop/colors.py
+++ b/bebop/colors.py
@@ -1,3 +1,5 @@
+"""Color definitions for curses."""
+
 import curses
 from enum import IntEnum
 
diff --git a/bebop/command_line.py b/bebop/command_line.py
index 20cf0f2..ee69153 100644
--- a/bebop/command_line.py
+++ b/bebop/command_line.py
@@ -1,3 +1,4 @@
+"""Integrated command-line implementation."""
 import curses
 import curses.textpad
 
diff --git a/bebop/gemtext.py b/bebop/gemtext.py
index 2b68009..a3492a8 100644
--- a/bebop/gemtext.py
+++ b/bebop/gemtext.py
@@ -1,3 +1,10 @@
+"""Gemtext parser.
+
+To allow a flexible rendering of the content, the parser produces a list of
+"elements", each being an instance of one of the dataclasses defined in this
+module. A renderer can then completely abstract the original document.
+"""
+
 import re
 import typing
 from dataclasses import dataclass
diff --git a/bebop/history.py b/bebop/history.py
index 2809286..f9b09ac 100644
--- a/bebop/history.py
+++ b/bebop/history.py
@@ -1,4 +1,7 @@
+"""History management."""
+
 class History:
+    """Basic browsing history manager."""
 
     def __init__(self):
         self.urls = []
diff --git a/bebop/mouse.py b/bebop/mouse.py
index e95f66e..48acc22 100644
--- a/bebop/mouse.py
+++ b/bebop/mouse.py
@@ -1,3 +1,5 @@
+"""Mouse support utilities."""
+
 from enum import IntEnum
 
 
diff --git a/bebop/navigation.py b/bebop/navigation.py
index 5cb21fa..1d2e712 100644
--- a/bebop/navigation.py
+++ b/bebop/navigation.py
@@ -1,3 +1,5 @@
+"""URI (RFC 3986) helpers for Gemini navigation."""
+
 import urllib.parse
 
 
@@ -42,7 +44,7 @@ def join_url(base_url: str, url: str):
 
 
 def set_parameter(url: str, user_input: str):
-    """Return a new URL with the user input escaped (RFC 3986) appended."""
+    """Return a new URL with the escaped user input appended."""
     quoted_input = urllib.parse.quote(user_input)
     if "?" in url:
         url = url.split("?", maxsplit=1)[0]
diff --git a/bebop/page.py b/bebop/page.py
index a047a85..eef7d77 100644
--- a/bebop/page.py
+++ b/bebop/page.py
@@ -1,3 +1,5 @@
+"""Single Gemini page curses management."""
+
 import curses
 
 from bebop.gemtext import parse_gemtext
diff --git a/bebop/protocol.py b/bebop/protocol.py
index bcab2ef..9e3ea6f 100644
--- a/bebop/protocol.py
+++ b/bebop/protocol.py
@@ -1,3 +1,5 @@
+"""Gemini protocol implementation."""
+
 import re
 import socket
 import ssl
@@ -18,7 +20,17 @@ def parse_gemini_url(url):
 
 
 class Request:
-    """A Gemini request."""
+    """A Gemini request.
+
+    Details about the request itself can be found in the Gemini specification.
+    This class allows you to do a request in 2 times: first opening the
+    TLS connection to apply security checks, then aborting or proceeding by
+    sending the request header and receiving the response:
+
+    1. Instantiate a Request.
+    2. `connect` opens the connection, leaves the caller free to check stuff.
+    3. `proceed` or `abort` can be called.
+    """
 
     # Initial state, connection is not established yet.
     STATE_INIT = 0
diff --git a/bebop/rendering.py b/bebop/rendering.py
index ec62766..33fa632 100644
--- a/bebop/rendering.py
+++ b/bebop/rendering.py
@@ -1,3 +1,10 @@
+"""Rendering Gemtext in curses.
+
+In Bebop we use a list of elements as produced by our parser. These elements are
+rendered into so-called "metalines", which are the text lines as they will be
+displayed, along with associated meta-data such as its type or a link's URL.
+"""
+
 import curses
 import string
 from enum import IntEnum
diff --git a/bebop/tofu.py b/bebop/tofu.py
index a89e715..8934d9c 100644
--- a/bebop/tofu.py
+++ b/bebop/tofu.py
@@ -1,3 +1,9 @@
+"""TOFU implementation.
+
+As of writing there is still some debate around it, so it is quite messy and
+requires more clarity both in specification and in our own implementation.
+"""
+
 import datetime
 import hashlib
 import re