revised documentations for corekit modules

docs/source/pcapkit/corekit/fields/collections.rst

@@ -10,3 +10,12 @@ Container Fields
 .. autoclass:: pcapkit.corekit.fields.collections.OptionField
    :members:
    :show-inheritance:
+
+Type Variables
+~~~~~~~~~~~~~~
+
+.. data:: pcapkit.corekit.fields.collections._TL
+   :type: pcapkit.protocols.schema.schema.Schema | pcapkit.corekit.fields.field.FieldBase | bytes
+
+.. data:: pcapkit.corekit.fields.collections._TS
+   :type: pcapkit.protocols.schema.schema.Schema

docs/source/pcapkit/corekit/fields/field.rst

@@ -0,0 +1,32 @@
+Base Fields
+===========
+
+.. module:: pcapkit.corekit.fields.field
+
+.. autoclass:: pcapkit.corekit.fields.field.Field
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.corekit.fields.field.FieldBase
+   :members:
+   :show-inheritance:
+
+Auxiliaries
+-----------
+
+.. autoclass:: pcapkit.corekit.fields.field.NoValueType
+.. autodata:: pcapkit.corekit.fields.field.NoValue
+   :no-value:
+
+Internal Definitions
+--------------------
+
+.. autoclass:: pcapkit.corekit.fields.field.FieldMeta
+   :members:
+   :show-inheritance:
+
+Type Variables
+--------------
+
+.. data:: pcapkit.corekit.fields.field._T
+   :type: typing.Any

docs/source/pcapkit/corekit/fields/index.rst

@@ -9,32 +9,106 @@ descriptive of the structure of protocol headers.
 .. toctree::
    :maxdepth: 2
 
+   field
    numbers
    strings
    ipaddress
    collections
    misc
 
-Base Fields
------------
+All field classes are implemented as :class:`~pcapkit.corekit.fields.field.FieldBase`
+subclasses, which are responsible for parsing and/or formatting the field value
+following the pre-defined mechanisms. Below is a brief diagram of the class
+hierarchy of :mod:`pcapkit.corekit.fields`:
 
-.. module:: pcapkit.corekit.fields.field
+.. mermaid::
 
-.. autoclass:: pcapkit.corekit.fields.field.FieldMeta
-   :members:
-   :show-inheritance:
+   flowchart LR
+       A{{FieldMeta}} -.->|metaclass| B(FieldBase)
+       B --> C(Field)
 
-.. autoclass:: pcapkit.corekit.fields.field.FieldBase
-   :members:
-   :show-inheritance:
+       subgraph numbers [Numerical Fields]
+           %% direction TD
 
-.. autoclass:: pcapkit.corekit.fields.field.Field
-   :members:
-   :show-inheritance:
+           NumberField --> Int64Field & UInt64Field
+           NumberField --> Int32Field & UInt32Field
+           NumberField --> Int16Field & UInt16Field
+           NumberField --> Int8Field & UInt8Field
+           NumberField --> EnumField
+       end
+       C --> NumberField
 
-Auxiliary
-~~~~~~~~~
+       subgraph strings [Text Fields]
+           %% direction TD
 
-.. autoclass:: pcapkit.corekit.fields.field.NoValueType
-.. autodata:: pcapkit.corekit.fields.field.NoValue
-   :no-value:
+           _TextField --> BytesField & StringField
+           _TextField --> BitField
+           BytesField --> PaddingField
+       end
+       C --> _TextField
+
+       subgraph ipaddress [IP Address Fields]
+           %% direction TD
+
+           _IPField --> _IPAddressField & _IPInterfaceField
+           _IPAddressField --> IPv4AddressField & IPv6AddressField
+           _IPInterfaceField --> IPv4InterfaceField & IPv6InterfaceField
+       end
+       C --> _IPField
+
+       subgraph collections [Container Fields]
+           %% direction TD
+
+           ListField --> OptionField
+       end
+       B --> ListField
+
+       subgraph misc [Miscellaneous Fields]
+           %% direction TD
+
+           NoValueField & ConditionalField & PayloadField
+           SwitchField & SchemaField & ForwardMatchField
+       end
+       B --> NoValueField & ConditionalField & PayloadField
+       B --> SwitchField & SchemaField & ForwardMatchField
+
+       C --> D([user customisation ...])
+
+       click A "/pcapkit/corekit/fields/field.html#pcapkit.corekit.fields.field.FieldMeta"
+       click B "/pcapkit/corekit/fields/field.html#pcapkit.corekit.fields.field.FieldBase"
+       click C "/pcapkit/corekit/fields/field.html#pcapkit.corekit.fields.field.Field"
+
+       click NumberField "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.NumberField"
+       click Int64Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.Int64Field"
+       click UInt64Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.UInt64Field"
+       click Int32Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.Int32Field"
+       click UInt32Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.UInt32Field"
+       click Int16Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.Int16Field"
+       click UInt16Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.UInt16Field"
+       click Int8Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.Int8Field"
+       click UInt8Field "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.UInt8Field"
+       click EnumField "/pcapkit/corekit/fields/numbers.html#pcapkit.corekit.fields.numbers.EnumField"
+
+       click _TextField "/pcapkit/corekit/fields/strings.html#pcapkit.corekit.fields.strings._TextField"
+       click BytesField "/pcapkit/corekit/fields/strings.html#pcapkit.corekit.fields.strings.BytesField"
+       click StringField "/pcapkit/corekit/fields/strings.html#pcapkit.corekit.fields.strings.StringField"
+       click BitField "/pcapkit/corekit/fields/strings.html#pcapkit.corekit.fields.strings.BitField"
+       click PaddingField "/pcapkit/corekit/fields/strings.html#pcapkit.corekit.fields.strings.PaddingField"
+
+       click _IPField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress._IPField"
+       click _IPAddressField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress._IPAddressField"
+       click _IPInterfaceField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress._IPInterfaceField"
+       click IPv4AddressField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress.IPv4AddressField"
+       click IPv6AddressField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress.IPv6AddressField"
+       click IPv4InterfaceField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress.IPv4InterfaceField"
+       click IPv6InterfaceField "/pcapkit/corekit/fields/ipaddress.html#pcapkit.corekit.fields.ipaddress.IPv6InterfaceField"
+
+       click ListField "/pcapkit/corekit/fields/collections.html#pcapkit.corekit.fields.collections.ListField"
+       click OptionField "/pcapkit/corekit/fields/collections.html#pcapkit.corekit.fields.collections.OptionField"
+
+       click NoValueField "/pcapkit/corekit/fields/misc.html#pcapkit.corekit.fields.misc.NoValueField"
+       click ConditionalField "/pcapkit/corekit/fields/misc.html#pcapkit.corekit.fields.misc.ConditionalField"
+       click PayloadField "/pcapkit/corekit/fields/misc.html#pcapkit.corekit.fields.misc.PayloadField"
+       click SwitchField "/pcapkit/corekit/fields/misc.html#pcapkit.corekit.fields.misc.SwitchField"
+       click SchemaField "/pcapkit/corekit/fields/misc.html#pcapkit.corekit.fields.misc.SchemaField"
+       click ForwardMatchField "/pcapkit/corekit/fields/misc.html#pcapkit.corekit.fields.misc.ForwardMatchField"

docs/source/pcapkit/corekit/fields/ipaddress.rst

@@ -3,17 +3,9 @@ IP Address Fields
 
 .. module:: pcapkit.corekit.fields.ipaddress
 
-.. autoclass:: pcapkit.corekit.fields.ipaddress._IPField
-   :members:
-   :show-inheritance:
-
 IP Addresses
 ~~~~~~~~~~~~
 
-.. autoclass:: pcapkit.corekit.fields.ipaddress._IPAddressField
-   :members:
-   :show-inheritance:
-
 .. autoclass:: pcapkit.corekit.fields.ipaddress.IPv4AddressField
    :members:
    :show-inheritance:
@@ -25,14 +17,37 @@ IP Addresses
 IP Interface
 ~~~~~~~~~~~~
 
-.. autoclass:: pcapkit.corekit.fields.ipaddress._IPInterfaceField
+.. autoclass:: pcapkit.corekit.fields.ipaddress.IPv4InterfaceField
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.corekit.fields.ipaddress.IPv4InterfaceField
+.. autoclass:: pcapkit.corekit.fields.ipaddress.IPv6InterfaceField
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.corekit.fields.ipaddress.IPv6InterfaceField
+Internal Definitions
+~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: pcapkit.corekit.fields.ipaddress._IPField
    :members:
    :show-inheritance:
+
+.. autoclass:: pcapkit.corekit.fields.ipaddress._IPAddressField
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.corekit.fields.ipaddress._IPInterfaceField
+   :members:
+   :show-inheritance:
+
+Type Variables
+~~~~~~~~~~~~~~
+
+.. data:: pcapkit.corekit.fields.ipaddress._T
+   :type: ipaddress.IPv4Address | ipaddress.IPv6Address | ipaddress.IPv4Interface | ipaddress.IPv6Interface
+
+.. data:: pcapkit.corekit.fields.ipaddress._AT
+   :type: ipaddress.IPv4Address | ipaddress.IPv6Address
+
+.. data:: pcapkit.corekit.fields.ipaddress._IT
+   :type: ipaddress.IPv4Interface | ipaddress.IPv6Interface

docs/source/pcapkit/corekit/fields/misc.rst

@@ -26,3 +26,18 @@ Miscellaneous Fields
 .. autoclass:: pcapkit.corekit.fields.misc.SchemaField
    :members:
    :show-inheritance:
+
+Type Variables
+~~~~~~~~~~~~~~
+
+.. data:: pcapkit.corekit.fields.misc._TC
+   :type: typing.Any
+
+.. data:: pcapkit.corekit.fields.misc._TS
+   :type: pcapkit.protocols.schema.schema.Schema
+
+.. data:: pcapkit.corekit.fields.misc._TP
+   :type: pcapkit.protocols.protocol.Protocol
+
+.. data:: pcapkit.corekit.fields.misc._TN
+   :type: pcapkit.corekit.fields.field.NoValueType

docs/source/pcapkit/corekit/fields/numbers.rst

@@ -1,11 +1,10 @@
 Numerical Fields
-----------------
+================
 
 .. module:: pcapkit.corekit.fields.numbers
 
-.. autoclass:: pcapkit.corekit.fields.numbers.NumberField
-   :members:
-   :show-inheritance:
+Sized Fields
+------------
 
 .. autoclass:: pcapkit.corekit.fields.numbers.Int32Field
    :members:
@@ -39,6 +38,22 @@ Numerical Fields
    :members:
    :show-inheritance:
 
+Enumeration Fields
+------------------
+
 .. autoclass:: pcapkit.corekit.fields.numbers.EnumField
    :members:
    :show-inheritance:
+
+Internal Definitions
+--------------------
+
+.. autoclass:: pcapkit.corekit.fields.numbers.NumberField
+   :members:
+   :show-inheritance:
+
+Type Variables
+--------------
+
+.. data:: pcapkit.corekit.fields.numbers._T
+   :type: int

docs/source/pcapkit/corekit/fields/strings.rst

@@ -1,16 +1,22 @@
 Text Fields
------------
+===========
 
 .. module:: pcapkit.corekit.fields.strings
 
-.. autoclass:: pcapkit.corekit.fields.strings._TextField
+Bytes-based Fields
+------------------
+
+.. autoclass:: pcapkit.corekit.fields.strings.BytesField
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.corekit.fields.strings.BytesField
+.. autoclass:: pcapkit.corekit.fields.strings.PaddingField
    :members:
    :show-inheritance:
 
+String-based Fields
+-------------------
+
 .. autoclass:: pcapkit.corekit.fields.strings.StringField
    :members:
    :show-inheritance:
@@ -19,6 +25,15 @@ Text Fields
    :members:
    :show-inheritance:
 
-.. autoclass:: pcapkit.corekit.fields.strings.PaddingField
+Internal Definitions
+--------------------
+
+.. autoclass:: pcapkit.corekit.fields.strings._TextField
    :members:
    :show-inheritance:
+
+Type Variables
+--------------
+
+.. data:: pcapkit.corekit.fields.strings._T
+   :type: str | bytes | dict[str, typing.Any]

docs/source/pcapkit/corekit/infoclass.rst

@@ -24,9 +24,18 @@ in :pep:`557`.
 
 .. autodecorator:: pcapkit.corekit.infoclass.info_final
 
-Meta Classes
-------------
+Internal Definitions
+--------------------
 
 .. autoclass:: pcapkit.corekit.infoclass.InfoMeta
    :no-members:
    :show-inheritance:
+
+Type Variables
+--------------
+
+.. data:: pcapkit.corekit.infoclass.VT
+   :type: typing.Any
+
+.. data:: pcapkit.corekit.infoclass.ST
+   :type: typing.Type[pcapkit.corekit.infoclass.Info]

docs/source/pcapkit/corekit/module.rst

@@ -22,3 +22,9 @@ which is originally designed as :obj:`tuple[str, str] <tuple>`.
       :type: str
 
       Class name.
+
+Type Variables
+--------------
+
+.. data:: pcapkit.corekit.module._T
+   :type: typing.Any

docs/source/pcapkit/corekit/multidict.rst

@@ -35,3 +35,15 @@ is inspired and based on the `Werkzeug`_ project.
    :no-members:
    :no-special-members: __init__
    :show-inheritance:
+
+Type Variables
+--------------
+
+.. data:: pcapkit.corekit.multidict._T
+   :type: typing.Any
+
+.. data:: pcapkit.corekit.multidict._KT
+   :type: typing.Any
+
+.. data:: pcapkit.corekit.multidict._VT
+   :type: typing.Any

docs/source/pcapkit/foundation/engines/engine.rst

@@ -58,3 +58,9 @@ Internal Definitions
 .. autoclass:: pcapkit.foundation.engines.engine.EngineMeta
    :no-members:
    :show-inheritance:
+
+Type Variables
+--------------
+
+.. data:: pcapkit.foundation.engines.engine._T
+   :type: typing.Any

docs/source/pcapkit/foundation/extraction.rst

@@ -78,6 +78,12 @@ extracts parametres from a PCAP file.
    .. automethod:: __next__
    .. automethod:: __call__
 
+Type Variables
+--------------
+
+.. data:: pcapkit.foundation.extraction._P
+   :type: typing.Any
+
 .. |pypcap| replace:: ``pypcap``
 .. _pypcap: https://pypcap.readthedocs.io/en/latest/
 .. |pycapfile| replace:: ``pycapfile``