chore: cite issues as #NNN in plain comments

docs/source/conf.py

@@ -178,7 +178,7 @@
 #     ``:class:`` or ``:func:`` cross-reference into them could ever resolve.
 #
 # Those packages are therefore linked to their project pages instead, through
-# :data:`rst_epilog` below (:issue:`1936`).
+# :data:`rst_epilog` below (#1936).
 
 #: The label on the note in :file:`pcapkit/foundation/engines/3rdparty.rst` that
 #: says which distribution installs the ``pcap`` module, which ``|pcap|_`` links
@@ -254,7 +254,7 @@
 # NB: a default renders as its source text rather than its ``repr()``. By value,
 # every ``byteorder=sys.byteorder`` showed the build host's ``'little'``, and the
 # ``corekit.fields`` pages showed ``default=<pcapkit.corekit.sentinels.NoValueType
-# object>`` and ``callback=<function NumberField.<lambda>>`` (:issue:`1859`).
+# object>`` and ``callback=<function NumberField.<lambda>>`` (#1859).
 autodoc_preserve_defaults = True
 #autodoc_member_order = 'bysource'
 #autodoc_member_order = 'alphabetic'

pcapkit/const/reg/apptype/__init__.py

@@ -138,7 +138,7 @@ def __ne__(self, other: 'object') -> 'bool':
         return dict.__ne__(self, other)
 
     # NOTE: dict union is :pep:`584`, Python 3.9 and up, so a registry has it
-    # from 3.9 only, as :obj:`dict` does (GitHub issue :issue:`1694`): before
+    # from 3.9 only, as :obj:`dict` does (GitHub issue #1694): before
     # 3.9, ``|`` and ``|=`` raise dict's :exc:`TypeError` and import nothing.
     # ``|=`` stays dict's own, since it updates in place and reads no value.
     if sys.version_info >= (3, 9):  # pragma: no branch -- Python 3.9 and up

pcapkit/corekit/decorators.py

@@ -172,7 +172,7 @@ def behold(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_beholder':
             # the payload *past* the extension headers, so falling back to the
             # whole IPv6 payload would hold those headers twice, once in the
             # extension header chain and once more in this ``Raw``
-            # (:issue:`1471`).
+            # (#1471).
             file_ = cast('Optional[bytes]', kwargs.get('payload'))
             if file_ is None:
                 file_ = self._get_payload()

pcapkit/corekit/fields/numbers.py

@@ -781,7 +781,7 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'Stdli
                     return member
                 # NOTE: A registry member is shared, so the captured bits
                 # outside ``bit_length`` go on an unregistered copy of it
-                # rather than on the member itself (:issue:`1488`).
+                # rather than on the member itself (#1488).
                 attrs = {key: val for key, val in vars(member).items()
                          if key not in ('_name_', '_value_', '__reduce_ex__')}
                 attrs[_OUTSIDE_BITS] = record
@@ -1066,7 +1066,7 @@ def pre_process(self, value: 'int | AppType', packet: 'dict[str, Any]') -> 'int
         # NOTE: imported here rather than at module level, as
         # :mod:`pcapkit.const` itself imports :mod:`pcapkit.corekit`; and tested
         # against AppType rather than ``self._namespace``, as the
-        # per-transport copies this class replaced did (:issue:`1516`).
+        # per-transport copies this class replaced did (#1516).
         from pcapkit.const.reg.apptype import AppType  # pylint: disable=import-outside-toplevel
 
         if isinstance(value, AppType):

pcapkit/corekit/infoclass.py

@@ -160,7 +160,7 @@ def info_final(cls: 'ST', *, _finalised: 'bool' = True) -> 'ST':
     # ``Info`` class, rather than itself, plus that such class does not
     # override the ``__init__`` method of the meta class. A multi-mapping
     # :class:`Info` (:class:`_MultiInfo`) declares no fields and keeps the
-    # mapping constructor it inherits (:issue:`1484`).
+    # mapping constructor it inherits (#1484).
     if '__init__' not in cls.__dict__ and cls is not Info and not issubclass(cls, _MultiInfo):
         args_ = []  # type: list[str]
         dict_ = []  # type: list[str]
@@ -177,7 +177,7 @@ def info_final(cls: 'ST', *, _finalised: 'bool' = True) -> 'ST':
             # Python version: below 3.10 (bpo-43901), ``__annotations__`` of a
             # class declaring none is its nearest base's, so a field-less
             # subclass read Info's ``__finalised__``, ``__additional__`` and
-            # ``__excluded__`` as its fields (:issue:`1692`). See
+            # ``__excluded__`` as its fields (#1692). See
             # :func:`~pcapkit.utilities.compat.get_annotations`.
             for key in reversed(get_annotations(cls_)):
                 # NOTE: We skip duplicated annotations to avoid duplicate
@@ -498,7 +498,7 @@ def __update__(self, dict_: 'Optional[Mapping[str, VT] | Iterable[tuple[str, VT]
         # NOTE: A :class:`MultiDict` or :class:`OrderedMultiDict` held as a
         # *value* -- the option lists the parsers build -- is stored as a
         # :class:`MultiInfo` or :class:`OrderedMultiInfo`, so that a finalised
-        # instance holds no mutable mapping (:issue:`1484`).
+        # instance holds no mutable mapping (#1484).
 
         __name__ = type(self).__name__  # pylint: disable=redefined-builtin
 
@@ -945,7 +945,7 @@ def __eq__(self, other: 'object') -> 'bool':
         # in buckets -- it answered False where the OrderedMultiDict, asked the
         # other way round, answered True. The ordered side decides, as it does
         # for a bare MultiDict, which Python asks it first for being its
-        # subclass (:issue:`1484`).
+        # subclass (#1484).
         if isinstance(other, OrderedMultiDict):
             return NotImplemented
         return MultiDict.__eq__(self, other)
@@ -1016,7 +1016,7 @@ class OrderedMultiInfo(_MultiInfo[KT, VT], OrderedMultiDict[KT, VT]):
     # OrderedMultiDict's own. ``__ne__`` is not: OrderedMultiDict has none, and
     # dict's compares the internal buckets, so two equal option lists compared
     # ``!=`` as well as ``==``. It is :func:`_ne`, as for the exports
-    # (:issue:`1484`).
+    # (#1484).
     __getitem__ = OrderedMultiDict.__getitem__  # type: ignore[assignment]
     __iter__ = OrderedMultiDict.__iter__  # type: ignore[assignment]
     __len__ = OrderedMultiDict.__len__

pcapkit/corekit/io.py

@@ -515,7 +515,7 @@ def seek(self, offset: 'int', whence: 'int' = io.SEEK_SET, /) -> 'int':
                 #
                 # The gap is waited for and the rest is not, and the position is
                 # the target, or the end of the stream if that comes first -- not
-                # wherever an over-asking read happened to stop (:issue:`1586`).
+                # wherever an over-asking read happened to stop (#1586).
                 tmp_gap = min(self._tell - tmp_end, self._buffer_size)
                 tmp_len = min(max(tmp_gap, self._buffer_size // 4), self._buffer_size)
 

pcapkit/corekit/multidict.py

@@ -146,7 +146,7 @@ def __init__(self, mapping: 'Optional[MultiDict[_KT, _VT] | Mapping[_KT, _VT | l
             super().__init__()
         elif isinstance(mapping, MultiDict):
             # NOTE: a dict, not pairs: GraalPy's dict.__init__ stores pairs
-            # through __setitem__, wrapping each list in another (:issue:`1963`).
+            # through __setitem__, wrapping each list in another (#1963).
             super().__init__({k: vs[:] for k, vs in mapping.lists()})
         elif isinstance(mapping, cabc.Mapping):
             tmp = {}  # type: dict[_KT, list[_VT]]
@@ -171,7 +171,7 @@ def __getstate__(self) -> 'Any':
 
     def __setstate__(self, value: 'Any') -> 'None':
         super().clear()
-        # NOTE: a dict, not pairs, as in __init__ (GraalPy, :issue:`1963`).
+        # NOTE: a dict, not pairs, as in __init__ (GraalPy, #1963).
         super().update(dict(value))
 
     def __iter__(self) -> 'Iterator[_KT]':  # pylint: disable=useless-parent-delegation

pcapkit/foundation/engines/dpkt.py

@@ -356,7 +356,7 @@ def __iter__(self) -> 'Iterator[tuple[float | decimal.Decimal, bytes]]':
                     yield DecimalTimestamp(value, resolution, hdr.len), buf
                 else:
                     # at a precision of 64 digits, not the caller's, which may
-                    # be too low to hold it (:issue:`1668`)
+                    # be too low to hold it (#1668)
                     with localcontext(prec=64):
                         exact = decimal.Decimal(hdr.tv_sec) + decimal.Decimal(hdr.tv_usec) / resolution
                     yield Timestamp(value, exact, resolution, hdr.len), buf
@@ -556,7 +556,7 @@ def read_frame(self) -> 'DPKTPacket':
             # more than its own ``UnpackError`` while parsing -- dpkt 1.9.8 reads
             # ``frag_off`` from whatever header follows an IPv6 Fragment header,
             # so a Fragment header followed by ESP or Destination Options raises
-            # :exc:`AttributeError` (:issue:`1351`). The frame is kept as a raw
+            # :exc:`AttributeError` (#1351). The frame is kept as a raw
             # packet, so one undecodable frame neither ends the extraction nor
             # shifts the numbering of the frames after it.
             warn(f'Frame {ext._frnum + 1}: dpkt cannot parse the frame '

pcapkit/foundation/extraction.py

@@ -311,7 +311,7 @@ class Extractor(Generic[_P]):
 
     # Read-only copies of the registries as shipped. A public registrar
     # handed the built-in a name shipped with restores this entry, so an
-    # override can be undone (:issue:`1363`).
+    # override can be undone (#1363).
     _shipped_output = types.MappingProxyType(dict(__output__))
     _shipped_engine = types.MappingProxyType(dict(__engine__))
     _shipped_reassembly = types.MappingProxyType(dict(__reassembly__))
@@ -1466,7 +1466,7 @@ def __init__(self,
         if len(self._magic) < 4:
             # NOTE: ``peek`` makes at most one read of the stream, which a pipe or a
             # raw stream may answer with fewer than four octets, so a short peek is
-            # not a short file. Read them instead, and seek back (:issue:`1586`).
+            # not a short file. Read them instead, and seek back (#1586).
             position = self._ifile.tell()
             self._magic = self._ifile.read(4)
             self._ifile.seek(position, os.SEEK_SET)

pcapkit/foundation/reassembly/ip.py

@@ -161,7 +161,7 @@ def reassembly(self, info: 'Packet[_AT]') -> 'None':
         # initialise buffer with BUFID; ``RCVBT`` holds one entry per 8-octet
         # block of the data buffer, its partial last block included -- 8191
         # covered octets 0 to 65527 only, so a fragment reaching octet 65528,
-        # e.g. at the largest Fragment Offset, indexed past it (:issue:`1565`)
+        # e.g. at the largest Fragment Offset, indexed past it (#1565)
         if BUFID not in self._buffer:
             self._buffer[BUFID] = Buffer(
                 TDL=-1,                              # Total Data Length
@@ -190,11 +190,11 @@ def reassembly(self, info: 'Packet[_AT]') -> 'None':
         #
         # A Total Length of 0 declares nothing. It is what TCP segmentation
         # offload leaves in a capture taken on the sending host, and the
-        # datagram then runs to the end of the captured frame (:issue:`1547`).
+        # datagram then runs to the end of the captured frame (#1547).
         # Wireshark ("presumed TSO") substitutes that length for the field
         # before it reassembles anything, and so does this, whatever **MF** and
         # the offset say: an unfragmented one is then whole rather than ``-IHL``
-        # octets long (:issue:`1555`). Linux's BIG TCP zeroes the field
+        # octets long (#1555). Linux's BIG TCP zeroes the field
         # precisely because the datagram, header included, outgrows the 65535
         # octets it can declare -- and such a datagram never completes in a
         # buffer of that length (:meth:`_is_complete`). So the buffer grows past
@@ -247,15 +247,15 @@ def reassembly(self, info: 'Packet[_AT]') -> 'None':
         #
         # * a truncated fragment's, since the octets after the cut are missing.
         #   That includes one clipped by the data buffer's end, whose octets
-        #   past it cannot be held, so it counts as cut there (:issue:`1566`).
+        #   past it cannot be held, so it counts as cut there (#1566).
         # * a non-final fragment's. :rfc:`791#section-3.2` and
         #   :rfc:`8200#section-4.5` make every fragment but the last carry a
         #   multiple of 8 octets, so one that ends mid-block was cut or is
         #   malformed, and nobody sent the rest of its block. Marking it would
         #   complete the datagram with zeros in their place. This is the only
         #   way a cut shows when the length is not declared: under Total
         #   Length 0, and on IPv6, whose adapters derive it from the captured
-        #   payload (:issue:`1567`).
+        #   payload (#1567).
         start = FO // 8
         if held == length and not MF:
             stop = (FO + held + 7) // 8
@@ -441,7 +441,7 @@ def submit(self, buf: 'Buffer[_AT]', *, bufid: 'tuple[_AT, _AT, int, TransType]'
                 data.append(bytes(byte))
             # Report it even with no run received, its payload ``()``, as
             # ``strict=False`` reports it with an empty payload: ``index``
-            # still says which frames were its fragments (:issue:`1566`).
+            # still says which frames were its fragments (#1566).
             packet = Datagram(
                 completed=completion,
                 id=DatagramID(

pcapkit/foundation/traceflow/traceflow.py

@@ -163,7 +163,7 @@ class TraceFlowBase(Generic[_DT, _BT, _IT, _PT], metaclass=TraceFlowMeta):
 
     # Read-only copy of ``__output__`` as shipped. :meth:`register_dumper`
     # handed the dumper a format shipped with restores this entry, so an
-    # override can be undone (:issue:`1363`).
+    # override can be undone (#1363).
     _shipped_output = types.MappingProxyType(dict(__output__))
 
     ##########################################################################

pcapkit/protocols/application/application.py

@@ -93,7 +93,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,
         super().__post_init__(file, length, **kwargs)  # type: ignore[arg-type]
 
         # NOTE: A header the data ends inside keeps that in its ``info``, so
-        # that :meth:`from_data` rebuilds only what was captured (:issue:`1458`).
+        # that :meth:`from_data` rebuilds only what was captured (#1458).
         keep_short_read(self)
 
         # ``read`` may have dispatched the undissected remainder through

pcapkit/protocols/application/ospf.py

@@ -209,7 +209,7 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_OSPF':
         # NOTE: Octets captured past the Packet Length belong to this layer,
         # since its own length field is what leaves them out of the payload --
         # the message digest of cryptographic authentication among them -- and
-        # the rebuild keeps them as captured (:issue:`1455`).
+        # the rebuild keeps them as captured (#1455).
         if schema.trailer:
             ospf.__update__([
                 ('trailer', schema.trailer),
@@ -360,7 +360,7 @@ def _make_data(cls, data: 'Data_OSPF') -> 'dict[str, Any]':  # type: ignore[over
             'auth_type': data.autype,
             'auth_data': data.auth,
             'payload': cls._make_payload(data),
-            # NOTE: And the octets captured past the Packet Length (:issue:`1455`).
+            # NOTE: And the octets captured past the Packet Length (#1455).
             'trailer': data.get('trailer', b''),
         }
 
@@ -473,7 +473,7 @@ def _make_encrypt_auth(self,
                 seq=auth_data.seq,
             )
         # NOTE: The ``to_dict()`` form of the info above, which ``from_data``
-        # passes through as is (:issue:`1464`).
+        # passes through as is (#1464).
         if isinstance(auth_data, dict):
             try:
                 return Schema_CryptographicAuthentication(

pcapkit/protocols/internet/hip.py

@@ -853,7 +853,7 @@ def _read_hip_param(self, length: 'int', *, version: 'int') -> 'Parameter':  # p
 
             # NOTE: The trailing padding (:rfc:`7401#section-5.2.1`) is kept on
             # the data model only when it is not all zeros -- the form a fresh
-            # build writes -- so that a rebuild reproduces it (:issue:`1223`).
+            # build writes -- so that a rebuild reproduces it (#1223).
             # :meth:`_make_hip_param` writes it back.
             padding = schema.__dict__.get('padding')
             if isinstance(padding, bytes) and any(padding):