add module docstrings

bebop/browser.py

@@ -1,3 +1,5 @@
+"""Main browser logic."""
+
 import curses
 import curses.ascii
 import curses.textpad

bebop/colors.py

@@ -1,3 +1,5 @@
+"""Color definitions for curses."""
+
 import curses
 from enum import IntEnum
 

bebop/command_line.py

@@ -1,3 +1,4 @@
+"""Integrated command-line implementation."""
 import curses
 import curses.textpad
 

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

bebop/history.py

@@ -1,4 +1,7 @@
+"""History management."""
+
 class History:
+    """Basic browsing history manager."""
 
     def __init__(self):
         self.urls = []

bebop/mouse.py

@@ -1,3 +1,5 @@
+"""Mouse support utilities."""
+
 from enum import IntEnum
 
 

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]

bebop/page.py

@@ -1,3 +1,5 @@
+"""Single Gemini page curses management."""
+
 import curses
 
 from bebop.gemtext import parse_gemtext

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

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

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