docs(internet): convert bare citations to the issue role in docstrings

pcapkit/protocols/internet/ah.py

@@ -51,7 +51,7 @@ class AH(IPsec[Data_AH, Schema_AH], IPv6_Ext[Data_AH, Schema_AH],
          schema=Schema_AH, data=Data_AH):
     """This class implements Authentication Header.
 
-    Double-inherited (GitHub issue #917): ``AH`` is both a member of the
+    Double-inherited (GitHub issue :issue:`917`): ``AH`` is both a member of the
     IPsec family and an IPv6 extension header -- IANA's *IPv6 Extension
     Header Types* registry lists it at 51 (:rfc:`4302#section-3.1.1` has
     it appear after the hop-by-hop, routing and fragmentation extension
@@ -86,7 +86,7 @@ def alias(self) -> 'Literal["AH"]':
         class-name default, because
         :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` now sits
         between this class and that default in the MRO and carries a concrete
-        ``'IPv6-Ext'`` of its own (GitHub issue #917). Inheriting it would
+        ``'IPv6-Ext'`` of its own (GitHub issue :issue:`917`). Inheriting it would
         rename this header in every
         :class:`~pcapkit.corekit.protochain.ProtoChain` string and in
         :meth:`IPv6._decode_next_layer

pcapkit/protocols/internet/esp.py

@@ -459,7 +459,7 @@ class ESPStatus(EnumLookup, enum.IntEnum):
     """Outcome of ESP payload processing.
 
     Re-parented onto :class:`~pcapkit.corekit.enum.EnumLookup` per GitHub
-    issue #930, finishing #877's phase 2 -- pure re-parenting, since this
+    issue :issue:`930`, finishing :issue:`877`'s phase 2 -- pure re-parenting, since this
     class defines neither ``get`` nor ``_missing_`` of its own to reconcile
     with the base.
 
@@ -525,7 +525,7 @@ class SecurityAssociation:
 
     Raises:
         ProtocolError: If the algorithms or key lengths are inconsistent, or
-            ``destination`` is a :obj:`bool` (c.f. #491) -- :obj:`bool` is an
+            ``destination`` is a :obj:`bool` (c.f. :issue:`491`) -- :obj:`bool` is an
             :class:`int` subclass, and :func:`ipaddress.ip_address` treats
             any :class:`int` below ``2**32`` as IPv4, so without this check
             ``destination=True`` would silently become
@@ -975,7 +975,7 @@ class ESP(IPsec[Data_ESP, Schema_ESP], IPv6_Ext[Data_ESP, Schema_ESP],
           schema=Schema_ESP, data=Data_ESP):
     """This class implements Encapsulating Security Payload.
 
-    Double-inherited (GitHub issue #917), mirroring
+    Double-inherited (GitHub issue :issue:`917`), mirroring
     :class:`~pcapkit.protocols.internet.ah.AH`: IANA's *IPv6 Extension
     Header Types* registry lists ``ESP`` at 50 (:rfc:`4303#section-3.1.1`
     has it appear after the hop-by-hop, routing and fragmentation
@@ -995,7 +995,7 @@ class ESP(IPsec[Data_ESP, Schema_ESP], IPv6_Ext[Data_ESP, Schema_ESP],
     Note:
         :rfc:`8200#section-4.5` says outright that ESP "is not considered an
         extension header". The library follows IANA's registry rather than
-        that sentence, on the owner's ruling for GitHub issue #895.
+        that sentence, on the owner's ruling for GitHub issue :issue:`895`.
 
     """
 

pcapkit/protocols/internet/hip.py

@@ -260,7 +260,7 @@ class HIP(IPv6_Ext[Data_HIP, Schema_HIP], Internet[Data_HIP, Schema_HIP],
     """This class implements Host Identity Protocol.
 
     Double-inherited, per the maintainer's convention given in review of the
-    work for #917: a header that is *only* usable as an extension header
+    work for :issue:`917`: a header that is *only* usable as an extension header
     inherits :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` alone,
     while one that is also usable as a standalone protocol names
     :class:`~pcapkit.protocols.internet.internet.Internet` as well. HIP is
@@ -3263,8 +3263,8 @@ def _make_puzzle_field_width(code: 'Enum_Parameter', version: 'int',
         Only case 4 can lose a leading zero octet, and it is the only case where the
         width is genuinely unknowable -- a from-scratch HIPv2 build with nothing
         declaring it. Reaching for it unconditionally is what re-serialised a
-        ``Length = 20`` ``SOLUTION`` as ``Length = 6`` (#653) and what built, under
-        HIPv1, parameters this library's own reader then rejected (#655).
+        ``Length = 20`` ``SOLUTION`` as ``Length = 6`` (:issue:`653`) and what built, under
+        HIPv1, parameters this library's own reader then rejected (:issue:`655`).
 
         Two things this deliberately does *not* reject, both of which look like
         oversights and are not:

pcapkit/protocols/internet/hopopt.py

@@ -231,7 +231,7 @@ def alias(self) -> 'Literal["HOPOPT"]':
         class-name default, because
         :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext` now sits
         between this class and that default in the MRO and carries a concrete
-        ``'IPv6-Ext'`` of its own (GitHub issue #917). Inheriting it would
+        ``'IPv6-Ext'`` of its own (GitHub issue :issue:`917`). Inheriting it would
         rename this header in every
         :class:`~pcapkit.corekit.protochain.ProtoChain` string and in
         :meth:`IPv6._decode_next_layer
@@ -487,8 +487,8 @@ def _hopopt_option_length(schema_len: 'int') -> 'int':
 
         Section 4.2 is the citation because it is what defines the TLV option
         format, and it is where the sentence quoted above actually appears.
-        This cited :rfc:`8200#section-4.3` until #530, which is a subtler
-        error than the one #517 fixed in the IPv6-Opts sibling: Section 4.3
+        This cited :rfc:`8200#section-4.3` until :issue:`530`, which is a subtler
+        error than the one :issue:`517` fixed in the IPv6-Opts sibling: Section 4.3
         is not the wrong *header* -- it is the Hop-by-Hop Options header,
         which is exactly what this class implements -- but it is the wrong
         place for this arithmetic. It defines no ``Opt Data Len`` at all,

pcapkit/protocols/internet/ipv4.py

@@ -1406,7 +1406,7 @@ def _make_opt_sec(self, kind: 'Enum_OptionNumber', option: 'Optional[Data_SECOpt
             :meth:`_read_opt_sec` encodes by looping over ``range(7)`` per
             octet, and the reason ``Field_Termination_Indicator`` is rejected
             here rather than written: the enumeration names it as structure, and
-            a value written there would be dropped on the way back in. See #537.
+            a value written there would be dropped on the way back in. See :issue:`537`.
 
         """
         if option is not None:

pcapkit/protocols/internet/ipv6.py

@@ -71,7 +71,7 @@ class IPv6(IP[Data_IPv6, Schema_IPv6],
     #: :func:`~pcapkit.utilities.decorators.beholder` fall back to plain
     #: :class:`~pcapkit.protocols.misc.raw.Raw`, which has no ``next`` field
     #: and used to crash the whole packet at :meth:`_decode_next_layer`'s
-    #: ``proto = info.next`` (GitHub issue #891).
+    #: ``proto = info.next`` (GitHub issue :issue:`891`).
     #:
     #: :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6`
     #: is deliberately absent, even though its wire format also conforms:
@@ -101,7 +101,7 @@ class IPv6(IP[Data_IPv6, Schema_IPv6],
     #: * ``253`` and ``254`` have no dedicated parser at all, so they resolve
     #:   to plain :class:`~pcapkit.protocols.misc.raw.Raw`, whose info has no
     #:   ``next`` *attribute* -- this is what the structural check catches.
-    #:   (``BIT-EMU``/147 used to sit here too, until GitHub issue #925 found
+    #:   (``BIT-EMU``/147 used to sit here too, until GitHub issue :issue:`925` found
     #:   it was never in IANA's authoritative extension-header registry to
     #:   begin with; :class:`~pcapkit.const.ipv6.extension_header
     #:   .ExtensionHeader` no longer carries it, so a next-header byte of 147
@@ -502,7 +502,7 @@ def _import_next_layer(self, proto: 'int', length: 'Optional[int]' = None, *,  #
             :class:`~pcapkit.protocols.misc.raw.Raw` -- and ``Raw`` has no
             ``next`` field, which is what used to crash the whole packet at
             :meth:`_decode_next_layer`'s ``proto = info.next`` (GitHub issue
-            #891). Every other exception -- including one raised by
+            :issue:`891`). Every other exception -- including one raised by
             ``IPv6_Ext`` itself, or by ``ESP``'s own dedicated
             parser -- still reaches ``beholder`` unchanged, so *this
             method's own* behaviour for anything outside that closed set is

pcapkit/protocols/internet/ipv6_ext.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.internet.ipv6_ext` contains
 :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`
-only, which serves two roles at once (GitHub issue #917): it is the
+only, which serves two roles at once (GitHub issue :issue:`917`): it is the
 shared **base class** of every IPv6 extension header in this package,
 and it implements a **generic** extractor for IPv6 extension headers,
 standing in for one whenever the header's own dedicated parser is
@@ -64,7 +64,7 @@
 This table classifies by *wire format* alone, over the eleven codes
 :class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader` enumerates --
 matching IANA's own *IPv6 Extension Header Types* registry exactly, as of
-GitHub issue #925. Before that fix this package generated the enumeration
+GitHub issue :issue:`925`. Before that fix this package generated the enumeration
 out of the *Protocol Numbers* registry's extension-header column instead,
 which carried a twelfth code, ``BIT_EMU`` (147), that the authoritative
 registry does not; 147 was never reachable through this class either way
@@ -110,14 +110,14 @@
    used to default it to plain :class:`~pcapkit.protocols.misc.raw.Raw` --
    which has no ``next`` field, so the walk in
    :meth:`IPv6._decode_next_layer <pcapkit.protocols.internet.ipv6.IPv6._decode_next_layer>`
-   crashed on it (GitHub issue #891). This module registers itself for that
+   crashed on it (GitHub issue :issue:`891`). This module registers itself for that
    code instead (see the bottom of the module), so dispatch reaches a
    working generic parser directly. That registration is global -- shared
    by every :class:`~pcapkit.protocols.internet.internet.Internet`
    subclass -- so :meth:`__post_init__` gates on ``version == 6`` to keep
    it from also activating for an IPv4 payload that happens to carry
    protocol number 140; see its docstring for what that would otherwise do.
-2. **A recognised header whose own parser raises.** This is the actual #891
+2. **A recognised header whose own parser raises.** This is the actual :issue:`891`
    defect: ``HOPOPT``, ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``,
    ``IPv6-Frag`` and ``AH`` all have dedicated classes, and when one of
    *those* raises, :func:`~pcapkit.utilities.decorators.beholder`
@@ -214,7 +214,7 @@ class IPv6_Ext(Internet[_PT, _ST], Generic[_PT, _ST],
     The two roles
     --------------
 
-    This one class plays both, on the owner's ruling for GitHub issue #917:
+    This one class plays both, on the owner's ruling for GitHub issue :issue:`917`:
 
     1. **The concrete fallback parser** for an :rfc:`6564`-conforming header
        this package has no dedicated class for, or whose dedicated class
@@ -311,7 +311,7 @@ def protocol(self) -> 'Optional[Enum_ExtensionHeader] | Optional[str]':
         module's own schema -- this is **not** the base
         :attr:`Protocol.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`
         meaning ("name of next layer protocol"); it is deliberately
-        repointed, on the owner's ruling for GitHub issue #891, at this
+        repointed, on the owner's ruling for GitHub issue :issue:`891`, at this
         instance's *own* identity -- which header's format it parsed, e.g.
         :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.HOPOPT`
         or :attr:`~pcapkit.const.ipv6.extension_header.ExtensionHeader.Shim6`.
@@ -357,7 +357,7 @@ def next(self) -> 'Optional[Enum_TransType]':
         Shared by every subclass rather than fallback-role-only -- see
         :class:`_NextHeaderData` for why that is sound. Note this is an
         *addition* for the eight implemented headers: none of them declared a
-        ``next`` property of its own before GitHub issue #917, so reading one
+        ``next`` property of its own before GitHub issue :issue:`917`, so reading one
         raised :exc:`AttributeError`, and nothing could have depended on a
         value it never returned.
 

pcapkit/protocols/internet/ipv6_opts.py

@@ -482,7 +482,7 @@ def _ipv6_opts_option_length(schema_len: 'int') -> 'int':
         IPv6-Opts itself is the Destination Options header of
         :rfc:`8200#section-4.6`, which carries those TLVs but says nothing
         about their internal length arithmetic. This cited
-        :rfc:`8200#section-4.3` until #517 -- that is the Hop-by-Hop Options
+        :rfc:`8200#section-4.3` until :issue:`517` -- that is the Hop-by-Hop Options
         header, which is a different header and not the one this class
         implements.
 

pcapkit/protocols/internet/ipv6_route.py

@@ -237,8 +237,8 @@ def _make_hdr_ext_len(data_length: 'int') -> 'int':
         is one helper now rather than two call sites. Do NOT "simplify" the
         ``- 4`` / ``/ 8`` away: the units either side of it differ (octets
         vs. 8-octet units), and dropping the offset silently reinterprets
-        the field, which is exactly the defect #487 fixed (compare the
-        ``* 8`` unit bug behind #483 in the scapy adapter).
+        the field, which is exactly the defect :issue:`487` fixed (compare the
+        ``* 8`` unit bug behind :issue:`483` in the scapy adapter).
 
         Args:
             data_length: packed length, in octets, of the type-specific data