fix(vendor): make wrapped const comments render as written (#1846, #1847)

pcapkit/const/http/status_code.py

@@ -58,8 +58,8 @@ def __str__(self) -> 'str':
     CODE_103 = 103, 'Early Hints'
 
     #: Upload Resumption Supported (TEMPORARY - registered 2024-11-13, extension
-    #: registered 2025-09-15, expires 2026-11-13) [draft-ietf-httpbis-resumable-
-    #: upload-05]
+    #: registered 2025-09-15, expires 2026-11-13)
+    #: [draft-ietf-httpbis-resumable-upload-05]
     CODE_104 = 104, 'Upload Resumption Supported'
 
     #: OK [:rfc:`9110#section-15.3.1`]

pcapkit/const/mh/dhcp_support_mode.py

@@ -29,7 +29,7 @@ class DHCPSupportMode(EnumRegistry, IntEnum):
     #: Unassigned
     Unassigned_0x0 = 0x0
 
-    #: (S) flag [:rfc:`5844`]
+    #: \(S) flag [:rfc:`5844`]
     S_flag = 0x1
 
     @classmethod

pcapkit/const/reg/apptype/apptype.py

@@ -1391,8 +1391,8 @@ class AppType(EnumRegistry, StrEnum):
          - [N/A] HP Remote Repository for Build and Test Results
        * - ``hpr-toollnx``
          - N/A
-         - [N/A] HP Remote System that houses compilers and tools for Linux-
-           based Systems
+         - [N/A] HP Remote System that houses compilers and tools for
+           Linux-based Systems
        * - ``hpr-toolwin``
          - N/A
          - [N/A] HP Remote System that houses compilers and tools for Microsoft
@@ -1909,8 +1909,8 @@ class AppType(EnumRegistry, StrEnum):
          - [N/A] Retrospect backup and restore service
        * - ``rfbc``
          - N/A
-         - [N/A] Remote Frame Buffer Client (Used by VNC viewers in listen-
-           mode)
+         - [N/A] Remote Frame Buffer Client (Used by VNC viewers in
+           listen-mode)
        * - ``rfid``
          - N/A
          - [N/A] RFID Reader Mach1(tm) Protocol

pcapkit/const/reg/apptype/tcp.py

@@ -76,8 +76,8 @@ class TCP(AppType):
        * - ``affinity-cntent``
          - [TCP] Affinity content sharing
        * - ``ai-adp``
-         - [TCP] AI Agent Discovery Protocol (ADP) [draft-pro-adp-agent-
-           discovery-00]
+         - [TCP] AI Agent Discovery Protocol (ADP)
+           [draft-pro-adp-agent-discovery-00]
        * - ``airdrop``
          - [TCP] Airdrop
        * - ``airmate``
@@ -151,8 +151,7 @@ class TCP(AppType):
          - [TCP] Data transfer service
        * - ``boardgame``
          - [TCP] Two-player board game play
-           [https://github.com/chentianren0/MiniXiangqi/blob/main/docs/boardgame-
-           protocol.md]
+           [https://github.com/chentianren0/MiniXiangqi/blob/main/docs/boardgame-protocol.md]
        * - ``boardplus``
          - [TCP] board plus application transfer protocol
        * - ``booked-sync``
@@ -209,8 +208,8 @@ class TCP(AppType):
        * - ``cerebra``
          - [TCP] Control the Cerebra Aquarium Controller
        * - ``certificates``
-         - [TCP] Server for S/MIME and PGP certificates [draft-
-           bhjl-x509-srv-01]
+         - [TCP] Server for S/MIME and PGP certificates
+           [draft-bhjl-x509-srv-01]
        * - ``ciao``
          - [TCP] Ciao Arduino Protocol
        * - ``collabio``
@@ -285,9 +284,9 @@ class TCP(AppType):
            "_dots-call-home._tcp" for discovering Call Home DOTS clients used
            to establish DOTS signal channel call home. [:rfc:`8973`]; [UDP]
            DOTS Signal Channel Call Home Protocol. The service name is used to
-           construct the SRV service names "_dots-call-home._udp" and "_dots-
-           call-home._tcp" for discovering Call Home DOTS clients used to
-           establish DOTS signal channel call home. [:rfc:`8973`]
+           construct the SRV service names "_dots-call-home._udp" and
+           "_dots-call-home._tcp" for discovering Call Home DOTS clients used
+           to establish DOTS signal channel call home. [:rfc:`8973`]
        * - ``dots-data``
          - [TCP] DOTS Data Channel Protocol. The service name is used to
            construct the SRV service name "_dots-data._tcp" for discovering
@@ -727,17 +726,17 @@ class TCP(AppType):
        * - ``smartsocket``
          - [TCP] home control
        * - ``smimeca``
-         - [TCP] Domain signing certificate for S/MIME keys [draft-
-           bhjl-x509-srv-01]
+         - [TCP] Domain signing certificate for S/MIME keys
+           [draft-bhjl-x509-srv-01]
        * - ``snif-cln``
-         - [TCP] SNIF End-to-End TLS Relay Client Connection [draft-zubov-
-           snif-05, Section 4.5]
+         - [TCP] SNIF End-to-End TLS Relay Client Connection
+           [draft-zubov-snif-05, Section 4.5]
        * - ``snif-fifo``
          - [TCP] SNIF End-to-End TLS Relay Cluster [draft-zubov-snif-05,
            Section 4.6]
        * - ``snif-srv``
-         - [TCP] SNIF End-to-End TLS Relay Service Connection [draft-zubov-
-           snif-05, Section 4.3]
+         - [TCP] SNIF End-to-End TLS Relay Service Connection
+           [draft-zubov-snif-05, Section 4.3]
        * - ``soda``
          - [TCP] Secure On Device API
        * - ``spidap``
@@ -20695,8 +20694,8 @@ class TCP(AppType):
     #: (Passive Optical Network) systems [TR-352][Inter-Channel-Termination
     #: protocol (ICTP) is a peer-to-peer protocol with a binary message format that
     #: is used by a set of optical line terminal (OLT) channel terminations (CT)
-    #: comprising a 40-Gigabit-capable next-generation passive optical network (NG-
-    #: PON2) system to exchange channel profile configuration and status
+    #: comprising a 40-Gigabit-capable next-generation passive optical network
+    #: (NG-PON2) system to exchange channel profile configuration and status
     #: information and to coordinate the operation of tunable optical network units
     #: (ONUs) in a multi-wavelength channel environment.]
     pon_ictp = 7202, 'pon-ictp', TransportProtocol.tcp
@@ -23287,8 +23286,8 @@ class TCP(AppType):
     linogridengine = 12300, 'linogridengine', TransportProtocol.tcp
 
     #: [TCP] Remote Administration Daemon (RAD) is a system service that offers
-    #: secure, remote, programmatic access to Solaris system configuration and run-
-    #: time state
+    #: secure, remote, programmatic access to Solaris system configuration and
+    #: run-time state
     rads = 12302, 'rads', TransportProtocol.tcp
 
     #: - [TCP] Warehouse Monitoring Syst SSS
@@ -24487,19 +24486,19 @@ class TCP(AppType):
     #: - [UDP] GameSmith Port
     gamesmith_port = 31765, 'gamesmith-port', TransportProtocol.tcp
 
-    #: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_tx".
+    #: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_tx".
     #: - [TCP] Embedded Device Configuration Protocol TX
-    #: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_tx".
+    #: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_tx".
     #: - [UDP] Embedded Device Configuration Protocol TX
     iceedcp_tx = 31948, 'iceedcp-tx', TransportProtocol.tcp
 
-    #: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_rx".
+    #: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_rx".
     #: - [TCP] Embedded Device Configuration Protocol RX
-    #: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_rx".
+    #: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_rx".
     #: - [UDP] Embedded Device Configuration Protocol RX
     iceedcp_rx = 31949, 'iceedcp-rx', TransportProtocol.tcp
 

pcapkit/const/reg/apptype/udp.py

@@ -142,9 +142,9 @@ class UDP(AppType):
            "_dots-call-home._tcp" for discovering Call Home DOTS clients used
            to establish DOTS signal channel call home. [:rfc:`8973`]; [UDP]
            DOTS Signal Channel Call Home Protocol. The service name is used to
-           construct the SRV service names "_dots-call-home._udp" and "_dots-
-           call-home._tcp" for discovering Call Home DOTS clients used to
-           establish DOTS signal channel call home. [:rfc:`8973`]
+           construct the SRV service names "_dots-call-home._udp" and
+           "_dots-call-home._tcp" for discovering Call Home DOTS clients used
+           to establish DOTS signal channel call home. [:rfc:`8973`]
        * - ``eb-sync``
          - [TCP] Easy Books App data sync helper for Mac OS X and iOS; [UDP]
            Easy Books App data sync helper for Mac OS X and iOS
@@ -23911,19 +23911,19 @@ class UDP(AppType):
     #: - [UDP] GameSmith Port
     gamesmith_port = 31765, 'gamesmith-port', TransportProtocol.udp
 
-    #: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_tx".
+    #: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_tx".
     #: - [TCP] Embedded Device Configuration Protocol TX
-    #: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_tx".
+    #: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_tx".
     #: - [UDP] Embedded Device Configuration Protocol TX
     iceedcp_tx = 31948, 'iceedcp-tx', TransportProtocol.udp
 
-    #: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_rx".
+    #: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_rx".
     #: - [TCP] Embedded Device Configuration Protocol RX
-    #: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this well-
-    #:   formed service name as a replacement for "iceedcp_rx".
+    #: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this
+    #:   well-formed service name as a replacement for "iceedcp_rx".
     #: - [UDP] Embedded Device Configuration Protocol RX
     iceedcp_rx = 31949, 'iceedcp-rx', TransportProtocol.udp
 

pcapkit/const/reg/linktype.py

@@ -527,12 +527,12 @@ class LinkType(EnumRegistry, IntEnum):
     #: [``DLT_NFLOG``] Linux netlink NETLINK NFLOG socket log messages.
     NFLOG = 239
 
-    #: [``DLT_NETANALYZER``] Ethernet frames with Hilscher netANALYZER pseudo-
-    #: header.
+    #: [``DLT_NETANALYZER``] Ethernet frames with Hilscher netANALYZER
+    #: pseudo-header.
     NETANALYZER = 240
 
-    #: [``DLT_NETANALYZER_TRANSPARENT``] Ethernet frames with netANALYZER pseudo-
-    #: header, preamble and SFD, preceded by a Hilscher.
+    #: [``DLT_NETANALYZER_TRANSPARENT``] Ethernet frames with netANALYZER
+    #: pseudo-header, preamble and SFD, preceded by a Hilscher.
     NETANALYZER_TRANSPARENT = 241
 
     #: [``DLT_IPOIB``] IP-over-InfiniBand.
@@ -544,8 +544,8 @@ class LinkType(EnumRegistry, IntEnum):
     #: [``DLT_NG40``] Frames from ng4T GmbH's ng40 protocol tester.
     NG40 = 244
 
-    #: [``DLT_NFC_LLCP``] NFC Logical Link Control Protocol frames, with a pseudo-
-    #: header.
+    #: [``DLT_NFC_LLCP``] NFC Logical Link Control Protocol frames, with a
+    #: pseudo-header.
     NFC_LLCP = 245
 
     #: Packet filter state syncing.
@@ -644,8 +644,8 @@ class LinkType(EnumRegistry, IntEnum):
     #: for Bluetooth LE packets.
     NORDIC_BLE = 272
 
-    #: [``DLT_DOCSIS31_XRA31``] DOCSIS packets and bursts, preceded by a pseudo-
-    #: header giving metadata about the packet.
+    #: [``DLT_DOCSIS31_XRA31``] DOCSIS packets and bursts, preceded by a
+    #: pseudo-header giving metadata about the packet.
     DOCSIS31_XRA31 = 273
 
     #: [``DLT_ETHERNET_MPACKET``] IEEE 802.3 mPackets.

pcapkit/const/reg/transtype.py

@@ -414,8 +414,8 @@ class TransType(EnumRegistry, IntEnum):
     #: Simple Message Protocol [Leif Ekblad]
     SMP = 121
 
-    #: Simple Multicast Protocol (deprecated)) [Jon Crowcroft][draft-perlman-
-    #: simple-multicast-03]
+    #: Simple Multicast Protocol (deprecated)) [Jon
+    #: Crowcroft][draft-perlman-simple-multicast-03]
     SM = 122
 
     #: Performance Transparency Protocol [Michael Welzl]

pcapkit/const/sctp/chunk.py

@@ -80,8 +80,8 @@ class Chunk(EnumRegistry, IntEnum):
     #: Payload Data supporting Interleaving (I-DATA) [:rfc:`8260`]
     Payload_Data_supporting_Interleaving = 64
 
-    #: DTLS (TEMPORARY - registered 2026-02-20, expires 2027-02-20) [draft-ietf-
-    #: tsvwg-sctp-dtls-chunk-01]
+    #: DTLS (TEMPORARY - registered 2026-02-20, expires 2027-02-20)
+    #: [draft-ietf-tsvwg-sctp-dtls-chunk-01]
     DTLS = 65
 
     #: Reserved for IETF-defined Chunk Extensions [:rfc:`9260`]

pcapkit/const/sctp/payload_protocol_identifier.py

@@ -79,8 +79,8 @@ class PayloadProtocolIdentifier(EnumRegistry, IntEnum):
     #: published.]
     Q_IPC_Q_2150_3 = 14
 
-    #: SIMCO <draft-kiesel-midcom-simco-sctp-00.txt> [draft-kiesel-midcom-simco-
-    #: sctp-00][Sebastian Kiesel]
+    #: SIMCO <draft-kiesel-midcom-simco-sctp-00.txt>
+    #: [draft-kiesel-midcom-simco-sctp-00][Sebastian Kiesel]
     SIMCO_draft_kiesel_midcom_simco_sctp_00_txt = 15
 
     #: DDP Segment Chunk [:rfc:`5043`]
@@ -241,7 +241,7 @@ class PayloadProtocolIdentifier(EnumRegistry, IntEnum):
     #: 3GPP E1 Application Protocol (E1AP) [         3GPP TS 38.463][Yang Xudong]
     PayloadProtocolIdentifier_3GPP_E1_Application_Protocol = 64
 
-    #: ELE2 Lawful Interception [http://ele2.io][Damir Franusic]
+    #: ELE2 Lawful Interception [http://ele2.io] [Damir Franusic]
     ELE2_Lawful_Interception = 65
 
     #: 3GPP NGAP over DTLS over SCTP [         3GPP TS 38.413][Yang Xudong]
@@ -268,8 +268,8 @@ class PayloadProtocolIdentifier(EnumRegistry, IntEnum):
     #: 3GPP W1AP [3GPP TS 37.473][Lionel Morand]
     PayloadProtocolIdentifier_3GPP_W1AP = 73
 
-    #: DTLS Chunk Key-Management Messages [draft-westerlund-tsvwg-sctp-dtls-
-    #: chunk-01]
+    #: DTLS Chunk Key-Management Messages
+    #: [draft-westerlund-tsvwg-sctp-dtls-chunk-01]
     DTLS_Chunk_Key_Management_Messages = 4242
 
     @classmethod

pcapkit/vendor/default.py

@@ -275,14 +275,38 @@ class Vendor(metaclass=VendorMeta):
     def wrap_comment(text: 'str') -> 'str':
         """Wraps long-length text to shorter lines of comments.
 
+        Sphinx renders a ``#:`` comment as reST, and its continuation lines
+        join into one paragraph, so the text is made safe for that first:
+
+        * a space goes after a URL reference that another bracket follows
+          directly, as in ``[http://ele2.io][Damir Franusic]``. docutils reads
+          ``]`` and ``[`` as URL characters, so the autolink would run on into
+          the next citation;
+        * a leading enumerator, such as the ``(S)`` of ``(S) flag``, is
+          backslash-escaped, since reST would render it as an enumerated list.
+
+        A line never breaks at a hyphen, which would render ``run-time`` as
+        ``run- time``. Only a word longer than a whole line is split inside.
+
+        .. versionchanged:: 1.5.0
+
+           Spaces a URL reference off the bracket after it and escapes a
+           leading enumerator (:issue:`1846`), and no longer breaks a line at a
+           hyphen (:issue:`1847`).
+
         Args:
             text: Source text.
 
         Returns:
             Wrapped comments.
 
         """
-        return '\n    #: '.join(textwrap.wrap(text.strip(), 76))
+        text = re.sub(r'(://[^\s\[\]]*\])(?=\[)', r'\1 ', text.strip())
+        # NOTE: the enumerator forms docutils recognises -- ``1.``, ``(a)``,
+        # ``iv)``, ``#.`` and so on -- each followed by a space or nothing.
+        text = re.sub(r'\A(?=(?:\((?:[0-9]+|[a-zA-Z]|[ivxlcdm]+|[IVXLCDM]+|#)\)'
+                      r'|(?:[0-9]+|[a-zA-Z]|[ivxlcdm]+|[IVXLCDM]+|#)[.)])(?: |\Z))', r'\\', text)
+        return '\n    #: '.join(textwrap.wrap(text, 76, break_on_hyphens=False))
 
     @staticmethod
     def split_references(text: 'str') -> 'list[str]':

pcapkit/vendor/reg/apptype/apptype.py

@@ -1099,14 +1099,27 @@ def count(self, data: 'list[str]') -> 'Counter[str]':
     def wrap_comment(text: 'str') -> 'str':
         """Wraps long-length text to shorter lines of comments.
 
+        The lines are :meth:`Vendor.wrap_comment`'s, so the text is made safe
+        for reST and never broken at a hyphen, the same way. Each continuation
+        takes a hanging indent instead, which keeps it inside the bullet a
+        merged entry renders it in.
+
+        .. versionchanged:: 1.5.0
+
+           Takes its lines from :meth:`Vendor.wrap_comment` rather than
+           wrapping on its own, so it no longer breaks a line at a hyphen
+           (:issue:`1847`) and escapes what that escapes (:issue:`1846`).
+
         Args:
             text: Source text.
 
         Returns:
             Wrapped comments.
 
         """
-        return '\n    #:   '.join(textwrap.wrap(text.strip(), 76))
+        # NOTE: textwrap turns every whitespace character into a space, so the
+        # only newlines in the base's output are the ones it joins lines with.
+        return Vendor.wrap_comment(text).replace('\n    #: ', '\n    #:   ')
 
     @staticmethod
     def flag(protos: 'Iterable[str]') -> 'str':
@@ -1135,6 +1148,14 @@ def tabulate(title: 'str', widths: 'tuple[int, ...]', header: 'tuple[str, ...]',
         :mod:`sphinx.ext.autodoc` renders in place rather than as comments it
         drops.
 
+        A cell breaks only at whitespace, never at a hyphen or inside a word:
+        its continuation lines join it with a space, so a URL split at a hyphen
+        would render as two words and lose the rest of its link.
+
+        .. versionchanged:: 1.5.0
+
+           No longer breaks a cell at a hyphen (:issue:`1847`).
+
         Args:
             title: Table caption.
             widths: Relative column widths.
@@ -1156,7 +1177,8 @@ def tabulate(title: 'str', widths: 'tuple[int, ...]', header: 'tuple[str, ...]',
         ]
         for row in [header, *rows]:
             for index, cell in enumerate(row):
-                wrapped = textwrap.wrap(cell, 68, break_long_words=False) or ['N/A']
+                wrapped = textwrap.wrap(cell, 68, break_long_words=False,
+                                        break_on_hyphens=False) or ['N/A']
                 bullet = '* - ' if not index else '  - '
                 lines.append(f'   {bullet}{wrapped[0]}')
                 lines.extend(f'       {part}' for part in wrapped[1:])