Rewrite Python comments in Google developer documentation style (#12)

* Rewrite comments in Google developer documentation style

Rewrite the comments and docstrings across the backend core modules so they
read plainly. The previous prose was accurate but dense and figurative, which
made it slow to skim.

Applies the Google developer documentation style guide: short sentences, active
voice, present tense, American spelling, and no metaphors, idioms, or
rhetorical asides. Replaces em-dash chains with separate sentences.

backend/app/accesslog.py

@@ -3,25 +3,25 @@
 The deliberate opposite of analytics.py. That module counts and stores nothing
 that points at a person; this one records addresses, email addresses and
 devices, because an access log that cannot identify the access is not an access
-log. They are kept in separate modules and separate tables on purpose — the
-anonymity of the counters is then a property of the code rather than of a
-convention someone has to remember.
+log. The two live in separate modules and separate tables on purpose, so that
+the anonymity of the counters is a property of the code rather than a convention
+someone has to remember.
 
 Owner-only, and never shown to the people it records.
 
 Four kinds of row:
 
-- `session`      a browser that has a session made a request — for a guest,
-                 their first visit;
-- `login`        an existing account signed in;
-- `register`     a guest upgraded to an account;
-- `login_failed` a password attempt that didn't match, with the address tried.
+- `session`      A browser that has a session made a request. For a guest, this
+                 is their first visit.
+- `login`        An existing account signed in.
+- `register`     A guest upgraded to an account.
+- `login_failed` A password attempt that did not match, with the address tried.
 
-Session rows are the only ones that need thinning: `/auth/me` runs on every
-page load, and a row per load would be noise rather than a log. One is written
-when the day or the address changes for that user, which is the granularity a
-log is actually read at — "seen on the 3rd from 1.2.3.4" — and it still catches
-someone moving networks mid-day.
+Session rows are the only ones that need thinning. `/auth/me` runs on every page
+load, and one row per load would be noise rather than a log. A row is written
+when the day or the address changes for that user. That is the granularity a log
+is read at, such as seen on the 3rd from 1.2.3.4, and it still records someone
+moving networks during a day.
 """
 
 import logging
@@ -50,31 +50,36 @@ _MAX_TRACKED = 10_000
 
 
 def _client_ip(request) -> str:
-    # Deferred: limits imports auth, which is imported by the routers that call
-    # this, so a module-level import here would close the loop. The spoof
-    # resistance lives there and must not be reimplemented — a second, laxer
-    # copy of "what is the client's address" is exactly how one of them ends up
-    # trusting a header it shouldn't.
+    # This import is deferred. `limits` imports `auth`, which the routers that
+    # call this function import, so a module-level import here would create a
+    # cycle. The spoof resistance lives in `limits` and must not be
+    # reimplemented. A second, looser answer to which address belongs to the
+    # client is how one of them ends up trusting a header it should not.
     from . import limits
 
     return limits.client_ip(request)
 
 
 def describe(user: models.User) -> str:
-    """How a user is named in the log. Guests have no email, and their id is
-    the only handle anyone has for them. The third case is a local install's
-    implicit single user, which is also email-less but is the operator rather
-    than a visitor — calling that one "Guest #1" would be a small lie in the
-    one row they are certain to read."""
+    """Returns how a user is named in the log.
+
+    A guest has no email, and their id is the only handle anyone has for them.
+    The third case is a local install's implicit single user, who also has no
+    email but is the operator rather than a visitor. Naming that user "Guest #1"
+    would be wrong in the one row they are certain to read.
+    """
     if user.email:
         return user.email
     return f"Guest #{user.id}" if user.is_guest else f"Local user #{user.id}"
 
 
 def _country(request) -> str:
-    """The edge's country header, or "" when there isn't one. Blank rather than
-    the counters' "(unknown)" label: a table column reads better as an em dash
-    than as a word, and an empty string is the honest value for "not known"."""
+    """Returns the edge's country header, or "" when there is none.
+
+    The blank differs from the counters' "(unknown)" label. A table column reads
+    better as a dash than as a word, and an empty string is the correct value for
+    a country that is not known.
+    """
     country = analytics.country_of(request.headers)
     return "" if country == analytics.UNKNOWN else country
 
@@ -87,8 +92,11 @@ def record(
     user: models.User | None = None,
     who: str | None = None,
 ) -> None:
-    """Write one row. Never raises: the log watches sign-in, it doesn't guard
-    it, and a logging failure must not be able to lock anyone out."""
+    """Writes one row.
+
+    This function never raises. The log observes sign-in rather than guarding it,
+    and a logging failure must not lock anyone out.
+    """
     try:
         event = models.AccessEvent(
             kind=kind,
@@ -108,7 +116,7 @@ def record(
 
 
 def note_session(db: Session, user: models.User, request) -> None:
-    """A session made a request. Thinned to one row per day per address."""
+    """Records that a session made a request, at most one row per day per address."""
     try:
         today = analytics._today()
         ip = _client_ip(request)
@@ -117,8 +125,8 @@ def note_session(db: Session, user: models.User, request) -> None:
                 return
             _last_session[user.id] = (today, ip)
             if len(_last_session) > _MAX_TRACKED:
-                # Nothing here is worth persisting; dropping the map costs at
-                # most one extra row per active user.
+                # Nothing here needs to persist. Clearing the map costs at most
+                # one extra row per active user.
                 _last_session.clear()
                 _last_session[user.id] = (today, ip)
     except Exception:  # pragma: no cover - defensive
@@ -135,11 +143,11 @@ def recent(
     kind: str | None = None,
     query: str | None = None,
 ) -> dict:
-    """A page of the log, newest first.
+    """Returns a page of the log, newest first.
 
-    Anchored on a row id rather than an offset, like the story pager: rows keep
-    arriving while it is being read, and an offset would shift the page under
-    whoever is reading it.
+    The page is anchored on a row id rather than an offset, as the story pager
+    is. Rows keep arriving while the log is read, and an offset would shift the
+    page under whoever is reading it.
     """
     statement = select(models.AccessEvent).order_by(desc(models.AccessEvent.id))
     if before_id is not None:
@@ -153,8 +161,8 @@ def recent(
             models.AccessEvent.ip.ilike(like),
             models.AccessEvent.country.ilike(like),
         ))
-    # One extra row answers "is there more" without a second COUNT over the
-    # whole table.
+    # Requesting one extra row reports whether more rows exist, without a
+    # second COUNT over the whole table.
     rows = list(db.scalars(statement.limit(limit + 1)))
     has_more = len(rows) > limit
     return {"events": rows[:limit], "has_more": has_more}