From 107af942e99ceb7156675eddbc6d48601ca46214 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <progval+git@progval.net>
Date: Sun, 10 Apr 2022 14:51:14 +0200
Subject: [PATCH] Add top-level docstrings to all modules

Will be used on the dashboard index in a future commit
---
 irctest/client_tests/cap.py                         |  2 ++
 irctest/client_tests/sasl.py                        |  5 +++++
 irctest/client_tests/tls.py                         |  2 ++
 irctest/self_tests/cases.py                         |  2 ++
 .../{register_verify.py => account_registration.py} |  5 +++++
 irctest/server_tests/account_tag.py                 |  2 +-
 irctest/server_tests/away.py                        | 13 +++++++++----
 irctest/server_tests/away_notify.py                 |  2 +-
 irctest/server_tests/bot_mode.py                    |  3 +--
 irctest/server_tests/bouncer.py                     |  6 ++++++
 irctest/server_tests/buffering.py                   |  6 ++++--
 irctest/server_tests/cap.py                         |  5 +++++
 irctest/server_tests/channel.py                     |  4 ++++
 irctest/server_tests/channel_forward.py             |  6 ++++++
 irctest/server_tests/channel_rename.py              |  4 ++++
 irctest/server_tests/chathistory.py                 |  4 ++++
 irctest/server_tests/chmodes/auditorium.py          |  6 ++++++
 irctest/server_tests/chmodes/ban.py                 |  9 ++++++++-
 irctest/server_tests/chmodes/ergo.py                |  4 ++++
 irctest/server_tests/chmodes/key.py                 |  7 +++++++
 irctest/server_tests/chmodes/moderated.py           |  6 ++++++
 irctest/server_tests/chmodes/mute_extban.py         |  4 ++++
 irctest/server_tests/chmodes/secret.py              |  7 +++++++
 irctest/server_tests/confusables.py                 |  5 +++++
 irctest/server_tests/connection_registration.py     |  2 ++
 irctest/server_tests/echo_message.py                |  2 +-
 irctest/server_tests/ergo/services.py               |  4 ++++
 irctest/server_tests/extended_join.py               |  2 +-
 irctest/server_tests/help.py                        |  2 +-
 irctest/server_tests/info.py                        |  5 ++++-
 irctest/server_tests/invite.py                      |  7 +++++++
 irctest/server_tests/isupport.py                    |  5 +++++
 irctest/server_tests/join.py                        |  7 +++++++
 irctest/server_tests/kick.py                        |  7 +++++++
 irctest/server_tests/labeled_responses.py           |  4 ++--
 irctest/server_tests/list.py                        |  9 +++++++++
 irctest/server_tests/lusers.py                      |  8 ++++++++
 irctest/server_tests/message_tags.py                |  2 +-
 irctest/server_tests/messages.py                    |  3 +--
 irctest/server_tests/metadata.py                    |  3 +--
 irctest/server_tests/monitor.py                     |  2 +-
 irctest/server_tests/multi_prefix.py                |  3 +--
 irctest/server_tests/multiline.py                   |  2 +-
 irctest/server_tests/names.py                       |  7 +++++++
 irctest/server_tests/part.py                        |  9 +++++++++
 irctest/server_tests/pingpong.py                    |  4 ++++
 irctest/server_tests/quit.py                        |  9 +++++++++
 irctest/server_tests/readq.py                       |  7 +++++--
 irctest/server_tests/regressions.py                 |  2 +-
 irctest/server_tests/relaymsg.py                    |  4 ++++
 irctest/server_tests/roleplay.py                    |  4 ++++
 irctest/server_tests/statusmsg.py                   |  7 +++++++
 irctest/server_tests/topic.py                       |  7 +++++++
 irctest/server_tests/utf8.py                        |  7 +++++++
 irctest/server_tests/wallops.py                     |  6 ++++++
 irctest/server_tests/who.py                         |  7 +++++++
 irctest/server_tests/whois.py                       |  6 ++++++
 irctest/server_tests/whowas.py                      | 10 ++++++++++
 irctest/server_tests/znc_playback.py                |  4 ++++
 59 files changed, 269 insertions(+), 29 deletions(-)
 rename irctest/server_tests/{register_verify.py => account_registration.py} (98%)

diff --git a/irctest/client_tests/cap.py b/irctest/client_tests/cap.py
index 5361945..03aa1a1 100644
--- a/irctest/client_tests/cap.py
+++ b/irctest/client_tests/cap.py
@@ -1,3 +1,5 @@
+"""Format of ``CAP LS`` sent by IRCv3 clients."""
+
 from irctest import cases
 from irctest.irc_utils.message_parser import Message
 
diff --git a/irctest/client_tests/sasl.py b/irctest/client_tests/sasl.py
index 7cc3781..bf766f9 100644
--- a/irctest/client_tests/sasl.py
+++ b/irctest/client_tests/sasl.py
@@ -1,3 +1,8 @@
+"""SASL authentication from clients, for all known mechanisms.
+
+For now, only `SASLv3.1 <https://ircv3.net/specs/extensions/sasl-3.1>`_
+is tested, not `SASLv3.2 <https://ircv3.net/specs/extensions/sasl-3.2>`_."""
+
 import base64
 
 import pytest
diff --git a/irctest/client_tests/tls.py b/irctest/client_tests/tls.py
index e24e421..285bd36 100644
--- a/irctest/client_tests/tls.py
+++ b/irctest/client_tests/tls.py
@@ -1,3 +1,5 @@
+"""Clients should validate certificates; either with a CA or fingerprints."""
+
 import socket
 import ssl
 
diff --git a/irctest/self_tests/cases.py b/irctest/self_tests/cases.py
index eda4b5d..63cf659 100644
--- a/irctest/self_tests/cases.py
+++ b/irctest/self_tests/cases.py
@@ -1,3 +1,5 @@
+"""Internal checks of assertion implementations."""
+
 from typing import Dict, List, Tuple
 
 import pytest
diff --git a/irctest/server_tests/register_verify.py b/irctest/server_tests/account_registration.py
similarity index 98%
rename from irctest/server_tests/register_verify.py
rename to irctest/server_tests/account_registration.py
index 805d373..ba8a25d 100644
--- a/irctest/server_tests/register_verify.py
+++ b/irctest/server_tests/account_registration.py
@@ -1,3 +1,8 @@
+"""
+`Draft IRCv3 account-registration
+<https://ircv3.net/specs/extensions/account-registration>`_
+"""
+
 from irctest import cases
 from irctest.patma import ANYSTR
 
diff --git a/irctest/server_tests/account_tag.py b/irctest/server_tests/account_tag.py
index ea909db..f5d2e87 100644
--- a/irctest/server_tests/account_tag.py
+++ b/irctest/server_tests/account_tag.py
@@ -1,5 +1,5 @@
 """
-<http://ircv3.net/specs/extensions/account-tag-3.2.html>
+`IRCv3 account-tag <https://ircv3.net/specs/extensions/account-tag>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/away.py b/irctest/server_tests/away.py
index 7b24a08..a6ea7b4 100644
--- a/irctest/server_tests/away.py
+++ b/irctest/server_tests/away.py
@@ -1,3 +1,8 @@
+"""
+AWAY command (`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-4.1>`__,
+`Modern <https://modern.ircdocs.horse/#away-message>`__)
+"""
+
 from irctest import cases
 from irctest.numerics import RPL_AWAY, RPL_NOWAWAY, RPL_UNAWAY, RPL_USERHOST
 from irctest.patma import StrRe
@@ -32,7 +37,7 @@ class AwayTestCase(cases.BaseServerTestCase):
         """
         "The server acknowledges the change in away status by returning the
         `RPL_NOWAWAY` and `RPL_UNAWAY` numerics."
-        -- https://github.com/ircdocs/modern-irc/pull/100
+        -- https://modern.ircdocs.horse/#away-message
         """
         self.connectClient("bar")
         self.sendLine(1, "AWAY :I'm not here right now")
@@ -48,7 +53,7 @@ class AwayTestCase(cases.BaseServerTestCase):
         """
         "Servers SHOULD notify clients when a user they're interacting with
         is away when relevant"
-        -- https://github.com/ircdocs/modern-irc/pull/100
+        -- https://modern.ircdocs.horse/#away-message
 
         "<client> <nick> :<message>"
         -- https://modern.ircdocs.horse/#rplaway-301
@@ -75,7 +80,7 @@ class AwayTestCase(cases.BaseServerTestCase):
         """
         "Servers SHOULD notify clients when a user they're interacting with
         is away when relevant"
-        -- https://github.com/ircdocs/modern-irc/pull/100
+        -- https://modern.ircdocs.horse/#away-message
 
         "<client> <nick> :<message>"
         -- https://modern.ircdocs.horse/#rplaway-301
@@ -113,7 +118,7 @@ class AwayTestCase(cases.BaseServerTestCase):
         """
         "Servers SHOULD notify clients when a user they're interacting with
         is away when relevant"
-        -- https://github.com/ircdocs/modern-irc/pull/100
+        -- https://modern.ircdocs.horse/#away-message
 
         "<client> <nick> :<message>"
         -- https://modern.ircdocs.horse/#rplaway-301
diff --git a/irctest/server_tests/away_notify.py b/irctest/server_tests/away_notify.py
index 6d3b8d6..283c007 100644
--- a/irctest/server_tests/away_notify.py
+++ b/irctest/server_tests/away_notify.py
@@ -1,5 +1,5 @@
 """
-<https://ircv3.net/specs/extensions/away-notify-3.1>
+`IRCv3 away-notify <https://ircv3.net/specs/extensions/away-notify>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/bot_mode.py b/irctest/server_tests/bot_mode.py
index 161aaf4..224c77e 100644
--- a/irctest/server_tests/bot_mode.py
+++ b/irctest/server_tests/bot_mode.py
@@ -1,6 +1,5 @@
 """
-Draft bot mode specification, as defined in
-<https://ircv3.net/specs/extensions/bot-mode>
+`IRCv3 draft bot mode <https://ircv3.net/specs/extensions/bot-mode>`_
 """
 
 from irctest import cases, runner
diff --git a/irctest/server_tests/bouncer.py b/irctest/server_tests/bouncer.py
index 4daed8d..c1cdc9f 100644
--- a/irctest/server_tests/bouncer.py
+++ b/irctest/server_tests/bouncer.py
@@ -1,3 +1,9 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests of
+`multiclient features
+<https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md#multiclient-bouncer>`_
+"""
+
 from irctest import cases
 from irctest.irc_utils.sasl import sasl_plain_blob
 from irctest.numerics import ERR_NICKNAMEINUSE, RPL_WELCOME
diff --git a/irctest/server_tests/buffering.py b/irctest/server_tests/buffering.py
index 321e04b..4adf01d 100644
--- a/irctest/server_tests/buffering.py
+++ b/irctest/server_tests/buffering.py
@@ -1,5 +1,7 @@
-"""Sends packets with various length to check the server reassembles them
-correctly. Also checks truncation"""
+"""
+Sends packets with various length to check the server reassembles them
+correctly. Also checks truncation.
+"""
 
 import socket
 import time
diff --git a/irctest/server_tests/cap.py b/irctest/server_tests/cap.py
index b4fd31d..1fd5a76 100644
--- a/irctest/server_tests/cap.py
+++ b/irctest/server_tests/cap.py
@@ -1,3 +1,8 @@
+"""
+`IRCv3 Capability negotiation
+<https://ircv3.net/specs/extensions/capability-negotiation>`_
+"""
+
 from irctest import cases
 from irctest.patma import ANYSTR
 from irctest.runner import CapabilityNotSupported, ImplementationChoice
diff --git a/irctest/server_tests/channel.py b/irctest/server_tests/channel.py
index 5fead80..61472f7 100644
--- a/irctest/server_tests/channel.py
+++ b/irctest/server_tests/channel.py
@@ -1,3 +1,7 @@
+"""
+Channel casemapping
+"""
+
 import pytest
 
 from irctest import cases, client_mock, runner
diff --git a/irctest/server_tests/channel_forward.py b/irctest/server_tests/channel_forward.py
index 9ce7312..11b284d 100644
--- a/irctest/server_tests/channel_forward.py
+++ b/irctest/server_tests/channel_forward.py
@@ -1,3 +1,9 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests of channel forwarding
+
+TODO: Should be extended to other servers, once a specification is written.
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_CHANOPRIVSNEEDED, ERR_INVALIDMODEPARAM, ERR_LINKCHANNEL
 
diff --git a/irctest/server_tests/channel_rename.py b/irctest/server_tests/channel_rename.py
index d22d950..b66fe59 100644
--- a/irctest/server_tests/channel_rename.py
+++ b/irctest/server_tests/channel_rename.py
@@ -1,3 +1,7 @@
+"""
+`Draft IRCv3 channel-rename <https://ircv3.net/specs/extensions/channel-rename>`_
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_CHANOPRIVSNEEDED
 
diff --git a/irctest/server_tests/chathistory.py b/irctest/server_tests/chathistory.py
index a387e6f..a264ae5 100644
--- a/irctest/server_tests/chathistory.py
+++ b/irctest/server_tests/chathistory.py
@@ -1,3 +1,7 @@
+"""
+`IRCv3 draft chathistory <https://ircv3.net/specs/extensions/chathistory>`_
+"""
+
 import secrets
 import time
 
diff --git a/irctest/server_tests/chmodes/auditorium.py b/irctest/server_tests/chmodes/auditorium.py
index 8cd74a3..bd328cb 100644
--- a/irctest/server_tests/chmodes/auditorium.py
+++ b/irctest/server_tests/chmodes/auditorium.py
@@ -1,3 +1,9 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests of auditorium mode
+
+TODO: Should be extended to other servers, once a specification is written.
+"""
+
 import math
 import time
 
diff --git a/irctest/server_tests/chmodes/ban.py b/irctest/server_tests/chmodes/ban.py
index 22cdebc..471e40a 100644
--- a/irctest/server_tests/chmodes/ban.py
+++ b/irctest/server_tests/chmodes/ban.py
@@ -1,3 +1,10 @@
+"""
+Channel ban (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.3.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.3>`__,
+`Modern <https://modern.ircdocs.horse/#ban-channel-mode>`__)
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_BANNEDFROMCHAN, RPL_BANLIST, RPL_ENDOFBANLIST
 from irctest.patma import ANYSTR, StrRe
@@ -26,7 +33,7 @@ class BanModeTestCase(cases.BaseServerTestCase):
 
     @cases.mark_specifications("Modern")
     def testBanList(self):
-        """https://github.com/ircdocs/modern-irc/pull/125"""
+        """`RPL_BANLIST <https://modern.ircdocs.horse/#rplbanlist-367>`"""
         self.connectClient("chanop")
         self.joinChannel(1, "#chan")
         self.getMessages(1)
diff --git a/irctest/server_tests/chmodes/ergo.py b/irctest/server_tests/chmodes/ergo.py
index eef9d11..ae4d26d 100644
--- a/irctest/server_tests/chmodes/ergo.py
+++ b/irctest/server_tests/chmodes/ergo.py
@@ -1,3 +1,7 @@
+"""
+Various Ergo-specific channel modes
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_CANNOTSENDTOCHAN, ERR_CHANOPRIVSNEEDED
 
diff --git a/irctest/server_tests/chmodes/key.py b/irctest/server_tests/chmodes/key.py
index eae1ab3..6878c90 100644
--- a/irctest/server_tests/chmodes/key.py
+++ b/irctest/server_tests/chmodes/key.py
@@ -1,3 +1,10 @@
+"""
+Channel key (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.3.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.3>`__,
+`Modern <https://modern.ircdocs.horse/#key-channel-mode>`__)
+"""
+
 import pytest
 
 from irctest import cases
diff --git a/irctest/server_tests/chmodes/moderated.py b/irctest/server_tests/chmodes/moderated.py
index e403dfe..d5b7b26 100644
--- a/irctest/server_tests/chmodes/moderated.py
+++ b/irctest/server_tests/chmodes/moderated.py
@@ -1,3 +1,9 @@
+"""
+Channel moderation mode (`RFC 2812
+<https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.3>`__,
+`Modern <https://modern.ircdocs.horse/#ban-channel-mode>`__)
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_CANNOTSENDTOCHAN
 
diff --git a/irctest/server_tests/chmodes/mute_extban.py b/irctest/server_tests/chmodes/mute_extban.py
index a17b0b4..5c3c6d4 100644
--- a/irctest/server_tests/chmodes/mute_extban.py
+++ b/irctest/server_tests/chmodes/mute_extban.py
@@ -1,3 +1,7 @@
+"""
+Mute extban, currently no specifications or ways to discover it.
+"""
+
 from irctest import cases, runner
 from irctest.numerics import ERR_CANNOTSENDTOCHAN, ERR_CHANOPRIVSNEEDED
 from irctest.patma import ANYLIST, StrRe
diff --git a/irctest/server_tests/chmodes/secret.py b/irctest/server_tests/chmodes/secret.py
index 15efaff..30f7759 100644
--- a/irctest/server_tests/chmodes/secret.py
+++ b/irctest/server_tests/chmodes/secret.py
@@ -1,3 +1,10 @@
+"""
+Channel secrecy mode (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.3.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.3>`__,
+`Modern <https://modern.ircdocs.horse/#secret-channel-mode>`__)
+"""
+
 from irctest import cases
 from irctest.numerics import RPL_LIST
 
diff --git a/irctest/server_tests/confusables.py b/irctest/server_tests/confusables.py
index 223d84b..480ece2 100644
--- a/irctest/server_tests/confusables.py
+++ b/irctest/server_tests/confusables.py
@@ -1,3 +1,8 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests for nick collisions based on Unicode
+confusable characters
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_NICKNAMEINUSE, RPL_WELCOME
 
diff --git a/irctest/server_tests/connection_registration.py b/irctest/server_tests/connection_registration.py
index 6a1df18..7bf6ffe 100644
--- a/irctest/server_tests/connection_registration.py
+++ b/irctest/server_tests/connection_registration.py
@@ -1,6 +1,8 @@
 """
 Tests section 4.1 of RFC 1459.
 <https://tools.ietf.org/html/rfc1459#section-4.1>
+
+TODO: cross-reference Modern and RFC 2812 too
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/echo_message.py b/irctest/server_tests/echo_message.py
index f183316..1da3412 100644
--- a/irctest/server_tests/echo_message.py
+++ b/irctest/server_tests/echo_message.py
@@ -1,5 +1,5 @@
 """
-<http://ircv3.net/specs/extensions/echo-message-3.2.html>
+`IRCv3 echo-message <https://ircv3.net/specs/extensions/echo-message>`_
 """
 
 import pytest
diff --git a/irctest/server_tests/ergo/services.py b/irctest/server_tests/ergo/services.py
index eb00ab2..ef877bd 100644
--- a/irctest/server_tests/ergo/services.py
+++ b/irctest/server_tests/ergo/services.py
@@ -1,3 +1,7 @@
+"""
+`Ergo <https://ergo.chat/>`-specific tests of NickServ.
+"""
+
 from irctest import cases
 from irctest.numerics import RPL_YOUREOPER
 
diff --git a/irctest/server_tests/extended_join.py b/irctest/server_tests/extended_join.py
index 7adf811..13dc975 100644
--- a/irctest/server_tests/extended_join.py
+++ b/irctest/server_tests/extended_join.py
@@ -1,5 +1,5 @@
 """
-<http://ircv3.net/specs/extensions/extended-join-3.1.html>
+`IRCv3 extended-join <https://ircv3.net/specs/extensions/extended-join>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/help.py b/irctest/server_tests/help.py
index c5acc65..9058ea3 100644
--- a/irctest/server_tests/help.py
+++ b/irctest/server_tests/help.py
@@ -1,5 +1,5 @@
 """
-The HELP and HELPOP command.
+The HELP and HELPOP command (`Modern <https://modern.ircdocs.horse/#help-message>`__)
 """
 
 import re
diff --git a/irctest/server_tests/info.py b/irctest/server_tests/info.py
index db0d9db..8e3ed61 100644
--- a/irctest/server_tests/info.py
+++ b/irctest/server_tests/info.py
@@ -1,5 +1,8 @@
 """
-The INFO command.
+The INFO command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.3.8>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.4.10>`__,
+`Modern <https://modern.ircdocs.horse/#info-message>`__)
 """
 
 import pytest
diff --git a/irctest/server_tests/invite.py b/irctest/server_tests/invite.py
index 8c07371..f441849 100644
--- a/irctest/server_tests/invite.py
+++ b/irctest/server_tests/invite.py
@@ -1,3 +1,10 @@
+"""
+The INVITE command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.7>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.7>`__,
+`Modern <https://modern.ircdocs.horse/#invite-message>`__)
+"""
+
 import pytest
 
 from irctest import cases
diff --git a/irctest/server_tests/isupport.py b/irctest/server_tests/isupport.py
index 40f087d..2c3cbaa 100644
--- a/irctest/server_tests/isupport.py
+++ b/irctest/server_tests/isupport.py
@@ -1,3 +1,8 @@
+"""
+RPL_ISUPPORT: `format <https://modern.ircdocs.horse/#rplisupport-005>`__
+and various `tokens <https://modern.ircdocs.horse/#rplisupport-parameters>`__
+"""
+
 import re
 
 from irctest import cases, runner
diff --git a/irctest/server_tests/join.py b/irctest/server_tests/join.py
index 673d403..e3433e6 100644
--- a/irctest/server_tests/join.py
+++ b/irctest/server_tests/join.py
@@ -1,3 +1,10 @@
+"""
+The JOIN command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.1>`__,
+`Modern <https://modern.ircdocs.horse/#join-message>`__)
+"""
+
 from irctest import cases
 from irctest.irc_utils import ambiguities
 
diff --git a/irctest/server_tests/kick.py b/irctest/server_tests/kick.py
index aaafcd5..d2acc72 100644
--- a/irctest/server_tests/kick.py
+++ b/irctest/server_tests/kick.py
@@ -1,3 +1,10 @@
+"""
+The INFO command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.>`__,
+`Modern <https://modern.ircdocs.horse/#kick-message>`__)
+"""
+
 import pytest
 
 from irctest import cases, client_mock, runner
diff --git a/irctest/server_tests/labeled_responses.py b/irctest/server_tests/labeled_responses.py
index f1c2374..03f9dfd 100644
--- a/irctest/server_tests/labeled_responses.py
+++ b/irctest/server_tests/labeled_responses.py
@@ -1,8 +1,8 @@
 """
+`IRCv3 labeled-response <https://ircv3.net/specs/extensions/labeled-response>`_
+
 This specification is a little hard to test because all labels are optional;
 so there may be many false positives.
-
-<https://ircv3.net/specs/extensions/labeled-response.html>
 """
 
 import re
diff --git a/irctest/server_tests/list.py b/irctest/server_tests/list.py
index 9529cb9..0c57289 100644
--- a/irctest/server_tests/list.py
+++ b/irctest/server_tests/list.py
@@ -1,3 +1,12 @@
+"""
+The LIST command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.6>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.6>`__,
+`Modern <https://modern.ircdocs.horse/#list-message>`__)
+
+TODO: check with Modern
+"""
+
 from irctest import cases
 
 
diff --git a/irctest/server_tests/lusers.py b/irctest/server_tests/lusers.py
index 58f3601..7eb59d6 100644
--- a/irctest/server_tests/lusers.py
+++ b/irctest/server_tests/lusers.py
@@ -1,3 +1,11 @@
+"""
+The LUSERS command  (`RFC 2812
+<https://datatracker.ietf.org/doc/html/rfc2812#section-3.4.2>`__,
+`Modern <https://modern.ircdocs.horse/#lusers-message>`__),
+which provides statistics on user counts.
+"""
+
+
 from dataclasses import dataclass
 import re
 from typing import Optional
diff --git a/irctest/server_tests/message_tags.py b/irctest/server_tests/message_tags.py
index 9d7ba14..e19a2d9 100644
--- a/irctest/server_tests/message_tags.py
+++ b/irctest/server_tests/message_tags.py
@@ -1,5 +1,5 @@
 """
-https://ircv3.net/specs/extensions/message-tags.html
+`IRCv3 message-tags <https://ircv3.net/specs/extensions/message-tags>`_
 """
 
 import pytest
diff --git a/irctest/server_tests/messages.py b/irctest/server_tests/messages.py
index 7f26025..a4e8544 100644
--- a/irctest/server_tests/messages.py
+++ b/irctest/server_tests/messages.py
@@ -1,6 +1,5 @@
 """
-Section 3.2 of RFC 2812
-<https://tools.ietf.org/html/rfc2812#section-3.3>
+The PRIVMSG and NOTICE commands.
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/metadata.py b/irctest/server_tests/metadata.py
index 6317c5e..abfde8b 100644
--- a/irctest/server_tests/metadata.py
+++ b/irctest/server_tests/metadata.py
@@ -1,6 +1,5 @@
 """
-Tests METADATA features.
-<http://ircv3.net/specs/core/metadata-3.2.html>
+`Deprecated IRCv3 Metadata <https://ircv3.net/specs/core/metadata-3.2>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/monitor.py b/irctest/server_tests/monitor.py
index 56e0306..211ee67 100644
--- a/irctest/server_tests/monitor.py
+++ b/irctest/server_tests/monitor.py
@@ -1,5 +1,5 @@
 """
-<http://ircv3.net/specs/core/monitor-3.2.html>
+`IRCv3 MONITOR <https://ircv3.net/specs/extensions/monitor>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/multi_prefix.py b/irctest/server_tests/multi_prefix.py
index 02e7aa9..1861ac7 100644
--- a/irctest/server_tests/multi_prefix.py
+++ b/irctest/server_tests/multi_prefix.py
@@ -1,6 +1,5 @@
 """
-Tests multi-prefix.
-<http://ircv3.net/specs/extensions/multi-prefix-3.1.html>
+`IRCv3 multi-prefix <https://ircv3.net/specs/extensions/multi-prefix>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/multiline.py b/irctest/server_tests/multiline.py
index 7e872df..ac4b7d5 100644
--- a/irctest/server_tests/multiline.py
+++ b/irctest/server_tests/multiline.py
@@ -1,5 +1,5 @@
 """
-draft/multiline
+`Draft IRCv3 multiline <https://ircv3.net/specs/extensions/multiline>`_
 """
 
 from irctest import cases
diff --git a/irctest/server_tests/names.py b/irctest/server_tests/names.py
index 628b2ac..5a79743 100644
--- a/irctest/server_tests/names.py
+++ b/irctest/server_tests/names.py
@@ -1,3 +1,10 @@
+"""
+The NAMES command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.5>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.5>`__,
+`Modern <https://modern.ircdocs.horse/#names-message>`__)
+"""
+
 from irctest import cases
 from irctest.numerics import RPL_ENDOFNAMES
 from irctest.patma import ANYSTR
diff --git a/irctest/server_tests/part.py b/irctest/server_tests/part.py
index acc2f86..59a2045 100644
--- a/irctest/server_tests/part.py
+++ b/irctest/server_tests/part.py
@@ -1,3 +1,12 @@
+"""
+The PART command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-6.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-5.2>`__,
+`Modern <https://modern.ircdocs.horse/#part-message>`__)
+
+TODO: cross-reference Modern
+"""
+
 import time
 
 from irctest import cases
diff --git a/irctest/server_tests/pingpong.py b/irctest/server_tests/pingpong.py
index 33dc4aa..0924d6b 100644
--- a/irctest/server_tests/pingpong.py
+++ b/irctest/server_tests/pingpong.py
@@ -1,3 +1,7 @@
+"""
+The PING and PONG commands
+"""
+
 from irctest import cases
 from irctest.numerics import ERR_NEEDMOREPARAMS, ERR_NOORIGIN
 from irctest.patma import ANYSTR
diff --git a/irctest/server_tests/quit.py b/irctest/server_tests/quit.py
index 8a7200d..022447f 100644
--- a/irctest/server_tests/quit.py
+++ b/irctest/server_tests/quit.py
@@ -1,3 +1,12 @@
+"""
+The QUITcommand  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.1.6>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.1>`__,
+`Modern <https://modern.ircdocs.horse/#quit-message>`__)
+
+TODO: cross-reference RFC 1459 and Modern
+"""
+
 import time
 
 from irctest import cases
diff --git a/irctest/server_tests/readq.py b/irctest/server_tests/readq.py
index 4e8182d..05eeeed 100644
--- a/irctest/server_tests/readq.py
+++ b/irctest/server_tests/readq.py
@@ -1,9 +1,12 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests of responses to DoS attacks
+using long lines.
+"""
+
 from irctest import cases
 
 
 class ReadqTestCase(cases.BaseServerTestCase):
-    """Test responses to DoS attacks using long lines."""
-
     @cases.mark_specifications("Ergo")
     @cases.mark_capabilities("message-tags")
     def testReadqTags(self):
diff --git a/irctest/server_tests/regressions.py b/irctest/server_tests/regressions.py
index 0361b3c..15ff21e 100644
--- a/irctest/server_tests/regressions.py
+++ b/irctest/server_tests/regressions.py
@@ -1,5 +1,5 @@
 """
-Regression tests for bugs in oragono.
+Regression tests for bugs in `Ergo <https://ergo.chat/>`_.
 """
 
 import time
diff --git a/irctest/server_tests/relaymsg.py b/irctest/server_tests/relaymsg.py
index 07df252..18af038 100644
--- a/irctest/server_tests/relaymsg.py
+++ b/irctest/server_tests/relaymsg.py
@@ -1,3 +1,7 @@
+"""
+RELAYMSG command of `Ergo <https://ergo.chat/>`_
+"""
+
 from irctest import cases
 from irctest.irc_utils.junkdrawer import random_name
 from irctest.patma import ANYSTR
diff --git a/irctest/server_tests/roleplay.py b/irctest/server_tests/roleplay.py
index 6ccfd68..2387ced 100644
--- a/irctest/server_tests/roleplay.py
+++ b/irctest/server_tests/roleplay.py
@@ -1,3 +1,7 @@
+"""
+Roleplay features of `Ergo <https://ergo.chat/>`_
+"""
+
 from irctest import cases
 from irctest.irc_utils.junkdrawer import random_name
 from irctest.numerics import ERR_CANNOTSENDRP
diff --git a/irctest/server_tests/statusmsg.py b/irctest/server_tests/statusmsg.py
index 7a07a2b..fb063f8 100644
--- a/irctest/server_tests/statusmsg.py
+++ b/irctest/server_tests/statusmsg.py
@@ -1,3 +1,10 @@
+"""
+STATUSMSG ISUPPORT token and related PRIVMSG (`Modern
+<https://modern.ircdocs.horse/#statusmsg-parameter>`__)
+
+TODO: cross-reference Modern
+"""
+
 from irctest import cases, runner
 from irctest.numerics import RPL_NAMREPLY
 
diff --git a/irctest/server_tests/topic.py b/irctest/server_tests/topic.py
index 4d83604..9489571 100644
--- a/irctest/server_tests/topic.py
+++ b/irctest/server_tests/topic.py
@@ -1,3 +1,10 @@
+"""
+The TOPIC command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.2.1>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.2.1>`__,
+`Modern <https://modern.ircdocs.horse/#topic-message>`__)
+"""
+
 from irctest import cases, client_mock, runner
 from irctest.numerics import ERR_CHANOPRIVSNEEDED, RPL_NOTOPIC, RPL_TOPIC, RPL_TOPICTIME
 
diff --git a/irctest/server_tests/utf8.py b/irctest/server_tests/utf8.py
index 46c838b..32ff563 100644
--- a/irctest/server_tests/utf8.py
+++ b/irctest/server_tests/utf8.py
@@ -1,3 +1,10 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests of non-Unicode filtering
+
+TODO: turn this into a test of `IRCv3 UTF8ONLY
+<https://ircv3.net/specs/extensions/utf8-only>`_
+"""
+
 from irctest import cases
 from irctest.patma import ANYSTR
 
diff --git a/irctest/server_tests/wallops.py b/irctest/server_tests/wallops.py
index 2d5fb69..c1d493b 100644
--- a/irctest/server_tests/wallops.py
+++ b/irctest/server_tests/wallops.py
@@ -1,3 +1,9 @@
+"""
+The WALLOPS command  (`RFC 2812
+<https://datatracker.ietf.org/doc/html/rfc2812#section-3.7>`__,
+`Modern <https://modern.ircdocs.horse/#wallops-message>`__)
+"""
+
 from irctest import cases, runner
 from irctest.numerics import ERR_NOPRIVILEGES, ERR_UNKNOWNCOMMAND, RPL_YOUREOPER
 from irctest.patma import ANYSTR, StrRe
diff --git a/irctest/server_tests/who.py b/irctest/server_tests/who.py
index c526b0d..e320cb1 100644
--- a/irctest/server_tests/who.py
+++ b/irctest/server_tests/who.py
@@ -1,3 +1,10 @@
+"""
+The WHO command  (`Modern <https://modern.ircdocs.horse/#who-message>`__)
+and `IRCv3 WHOX <https://ircv3.net/specs/extensions/whox>`_
+
+TODO: cross-reference RFC 1459 and RFC 2812
+"""
+
 import re
 
 import pytest
diff --git a/irctest/server_tests/whois.py b/irctest/server_tests/whois.py
index 8a0ef3a..a23ee66 100644
--- a/irctest/server_tests/whois.py
+++ b/irctest/server_tests/whois.py
@@ -1,3 +1,9 @@
+"""
+The WHOIS command  (`Modern <https://modern.ircdocs.horse/#whois-message>`__)
+
+TODO: cross-reference RFC 1459 and RFC 2812
+"""
+
 import pytest
 
 from irctest import cases
diff --git a/irctest/server_tests/whowas.py b/irctest/server_tests/whowas.py
index 2550432..dd65b54 100644
--- a/irctest/server_tests/whowas.py
+++ b/irctest/server_tests/whowas.py
@@ -1,3 +1,13 @@
+"""
+The WHOSWAS command  (`RFC 1459
+<https://datatracker.ietf.org/doc/html/rfc1459#section-4.5.3>`__,
+`RFC 2812 <https://datatracker.ietf.org/doc/html/rfc2812#section-3.6.3>`__,
+`Modern <https://modern.ircdocs.horse/#whowas-message>`__)
+
+TODO: cross-reference Modern
+"""
+
+
 import pytest
 
 from irctest import cases, runner
diff --git a/irctest/server_tests/znc_playback.py b/irctest/server_tests/znc_playback.py
index a5ac61f..ca00efd 100644
--- a/irctest/server_tests/znc_playback.py
+++ b/irctest/server_tests/znc_playback.py
@@ -1,3 +1,7 @@
+"""
+`Ergo <https://ergo.chat/>`_-specific tests of ZNC-like message playback
+"""
+
 import time
 
 from irctest import cases