Tweak documentation for type classes

LiteApplication · LiteApplication · commit d133a834c70f · 2024-06-18T18:42:20.000+02:00
diff --git a/docs/api/types/general.rst b/docs/api/types/general.rst
@@ -5,4 +5,7 @@ Here are documented the general types used throughout the Minecraft protocol.
 
 .. automodule:: mcproto.types
     :no-undoc-members:
-    :exclude-members: NBTag, StringNBT, CompoundNBT, EndNBT
+    :exclude-members: NBTag, StringNBT, CompoundNBT, EndNBT, EntityMetadata, UUID
+
+.. autoclass:: mcproto.types.UUID
+    :class-doc-from: class
diff --git a/docs/pages/installation.rst b/docs/pages/installation.rst
@@ -17,7 +17,7 @@ Latest (git) version
 
 Alternatively, you may want to install the latest available version, which is what you currently see in the ``main``
 git branch. Although this method will actually work for any branch with a pretty straightforward change. This kind of
-installation should only be done when testing new feautes, and it's likely you'll encounter bugs.
+installation should only be done when testing new features, and it's likely you'll encounter bugs.
 
 That said, since mcproto is still in development, changes can often be made pretty quickly, and it can sometimes take a
 while for these changes to carry over to PyPI. So if you really want to try out that latest feature, this is the method
diff --git a/mcproto/multiplayer.py b/mcproto/multiplayer.py
@@ -140,7 +140,7 @@ def compute_server_hash(server_id: str, shared_secret: bytes, server_public_key:
     need to know the encryption key (``shared_secret``). A proxy can capture this key, as the client
     sends it over to the server in :class:`~mcproto.packets.login.login.LoginEncryptionResponse` packet,
     however it is sent encrypted. The client performs this encryption with a public key, which it got
-    from the server, in :class:`mcproto.packets.login.login.LoginEncryptionRequest` packet.
+    from the server, in :class:`~mcproto.packets.login.login.LoginEncryptionRequest` packet.
 
     That mans that for a proxy to be able to actually obtain this shared secret value, it would need to
     be able to capture the encryption response, and decrypt the shared secret value. That means it would
diff --git a/mcproto/packets/login/login.py b/mcproto/packets/login/login.py
@@ -33,7 +33,8 @@ class LoginStart(ServerBoundPacket):
     Initialize the LoginStart packet.
 
     :param username: Username of the client who sent the request.
-    :param uuid: UUID of the player logging in (if the player doesn't have a UUID, this can be ``None``)
+    :param uuid: UUID of the player logging in (unused by the server)
+    :type uuid: :class:`~mcproto.types.UUID`
     """
 
     PACKET_ID: ClassVar[int] = 0x00
@@ -143,7 +144,9 @@ class LoginSuccess(ClientBoundPacket):
     Initialize the LoginSuccess packet.
 
     :param uuid: The UUID of the connecting player/client.
+    :type uuid: :class:`~mcproto.types.UUID`
     :param username: The username of the connecting player/client.
+    :type username: str
     """
 
     PACKET_ID: ClassVar[int] = 0x02
diff --git a/mcproto/types/advancement.py b/mcproto/types/advancement.py
@@ -21,7 +21,7 @@ class Advancement(MCType):
     https://wiki.vg/Protocol#Update_Advancements
 
     :param parent: The parent advancement.
-    :type parent: :class:`mcproto.types.identifier.Identifier`, optional
+    :type parent: :class:`~mcproto.types.identifier.Identifier`, optional
     :param display: The display information.
     :type display: :class:`AdvancementDisplay`, optional
     :param requirements: The criteria for this advancement.
@@ -62,14 +62,14 @@ class AdvancementDisplay(MCType):
     """Describes how an advancement should look.
 
     :param title: The title of the advancement.
-    :type title: :class:`mcproto.types.chat.TextComponent`
+    :type title: :class:`~mcproto.types.chat.TextComponent`
     :param description: The description of the advancement.
-    :type description: :class:`mcproto.types.chat.TextComponent`
+    :type description: :class:`~mcproto.types.chat.TextComponent`
     :param icon: The icon of the advancement.
-    :type icon: :class:`mcproto.types.slot.Slot`
+    :type icon: :class:`~mcproto.types.slot.Slot`
     :param frame: The frame of the advancement (0: task, 1: challenge, 2: goal).
     :param background: The background texture of the advancement.
-    :type background: :class:`mcproto.types.identifier.Identifier`, optional
+    :type background: :class:`~mcproto.types.identifier.Identifier`, optional
     :param show_toast: Whether to show a toast notification.
     :type show_toast: bool
     :param hidden: Whether the advancement is hidden.
@@ -136,7 +136,7 @@ class AdvancementProgress(MCType):
     """Represents the progress of an advancement.
 
     :param criteria: The criteria for this advancement.
-    :type criteria: dict[:class:`mcproto.types.identifier.Identifier`, :class:`AdvancementCriterion`]
+    :type criteria: dict[:class:`~mcproto.types.identifier.Identifier`, :class:`AdvancementCriterion`]
     """
 
     criteria: dict[Identifier, AdvancementCriterion]
diff --git a/mcproto/types/block_entity.py b/mcproto/types/block_entity.py
@@ -22,7 +22,7 @@ class BlockEntity(MCType):
     :type nbt: CompoundNBT
 
     .. warning:: The position must be within the chunk.
-    .. note :: This class is used in the :class:`mcproto.packets.play.ChunkData` packet.
+    .. note :: This class is used in the :class:`~mcproto.packets.play.ChunkData` packet.
     """
 
     position: Position
diff --git a/mcproto/types/entity/metadata.py b/mcproto/types/entity/metadata.py
@@ -372,13 +372,15 @@ class EntityMetadata(MCType, metaclass=EntityMetadataCreator):
     You can set attributes of the entity class by using the entry() and proxy() functions.
 
     Example:
-    ```python
-    class EntityMetadata(EntityMetadata):
-        byte_entry: ClassVar[int] = entry(ByteEME, 0) # ByteEME is the type and 0 is the default value
-        varint_entry: int = entry(VarIntEME, 0)
-        proxy_entry: int = proxy(byte_entry, Masked, mask=0x01)
-        proxy_entry2: int = proxy(byte_entry, Masked, mask=0x02)
-    ```
+
+    .. code-block:: python
+
+        class EntityMetadata(EntityMetadata):
+            byte_entry: ClassVar[int] = entry(ByteEME, 0) # ByteEME is the type and 0 is the default value
+            varint_entry: int = entry(VarIntEME, 0)
+            proxy_entry: int = proxy(byte_entry, Masked, mask=0x01)
+            proxy_entry2: int = proxy(byte_entry, Masked, mask=0x02)
+
 
     Note that the extra arguments for the proxy() function are passed to the proxy class and that the
     bound entry is passed as the first argument without quotes.
diff --git a/mcproto/types/identifier.py b/mcproto/types/identifier.py
@@ -17,7 +17,7 @@ class Identifier(MCType, NBTagConvertible):
     :param path: The path of the identifier.
     :type path: str, optional
 
-    If the path is not provided, the namespace and path will be extracted from the :arg:`namespace` argument.
+    If the path is not provided, the namespace and path will be extracted from the :attr:`namespace` argument.
     If the namespace is not provided, it will default to "minecraft".
     """
 
diff --git a/mcproto/types/modifier.py b/mcproto/types/modifier.py
@@ -29,12 +29,12 @@ class ModifierOperation(IntEnum):
 @final
 @define
 class ModifierData(MCType):
-    """Represents a modifier data in the :class:`mcproto.packets.play.UpdateAttributes` packet.
+    """Represents a modifier data in the :class:`~mcproto.packets.play.UpdateAttributes` packet.
 
     https://wiki.vg/Protocol#Update_Attributes
 
     :param uuid: The UUID of the modifier.
-    :type uuid: :class:`mcproto.types.uuid.UUID`
+    :type uuid: :class:`~mcproto.types.uuid.UUID`
     :param amount: The amount of the modifier.
     :type amount: float
     :param operation: The operation of the modifier.
diff --git a/mcproto/types/particle_data.py b/mcproto/types/particle_data.py
@@ -48,12 +48,12 @@ class ParticleData(MCType):
     :type roll: float, optional
 
     :param item: The item that will be displayed as a particle.
-    :type item: :class:`mcproto.types.item.Slot`, optional
+    :type item: :class:`~mcproto.types.item.Slot`, optional
 
     :param source_type: The type of the source of the particle. (0 for `minecraft:block`, 1 for `minecraft:entity`)
     :type source_type: int, optional
     :param block_position: The position of the block that is the source of the particle. (used when `source_type` is 0)
-    :type block_position: :class:`mcproto.types.vec3.Position`, optional
+    :type block_position: :class:`~mcproto.types.vec3.Position`, optional
     :param entity_id: The ID of the entity that is the source of the particle. (used when `source_type` is 1)
     :type entity_id: int, optional
     :param entity_eye_height: The height of the entity's eye relative to the entity. (used when `source_type` is 1)
diff --git a/mcproto/types/recipe.py b/mcproto/types/recipe.py
@@ -22,7 +22,7 @@ class Ingredient(MCType):
     :param count: The count of the item.
     :type count: int
     :param items: The items that can be used to craft the item.
-    :type items: list[:class:`mcproto.types.slot.Slot`]
+    :type items: list[:class:`~mcproto.types.slot.Slot`]
 
     .. note:: Each item in the list has to have a count of 1.
     """
@@ -52,12 +52,12 @@ def validate(self) -> None:
 
 @define
 class Recipe(MCType, RequiredParamsABCMixin):
-    """Represents a recipe in the :class:`mcproto.packets.play.UpdateRecipes` packet.
+    """Represents a recipe in the :class:`~mcproto.packets.play.UpdateRecipes` packet.
 
     https://wiki.vg/Protocol#Update_Recipes
 
     :param recipe_id: The ID of the recipe.
-    :type recipe_id: :class:`mcproto.types.identifier.Identifier`
+    :type recipe_id: :class:`~mcproto.types.identifier.Identifier`
     """
 
     _REQUIRED_CLASS_VARS = ("recipe_type",)
@@ -87,7 +87,7 @@ def deserialize(cls, buf: Buffer) -> Recipe:
 @final
 @define
 class ShapedRecipe(Recipe):
-    """Represents a shaped recipe in the :class:`mcproto.packets.play.UpdateRecipes` packet.
+    """Represents a shaped recipe in the :class:`~mcproto.packets.play.UpdateRecipes` packet.
 
     Shaped crafting recipe. All items must be present in the same pattern (which may be flipped horizontally or
     translated).
@@ -103,7 +103,7 @@ class ShapedRecipe(Recipe):
     :param ingredients: The ingredients of the recipe.
     :type ingredients: list[:class:`Ingredient`]
     :param result: The result of the recipe.
-    :type result: :class:`mcproto.types.slot.Slot`
+    :type result: :class:`~mcproto.types.slot.Slot`
     :param show_toast: Whether to show a toast notification when the recipe is unlocked.
     :type show_toast: bool
     """
@@ -157,7 +157,7 @@ def _deserialize(cls, buf: Buffer, recipe_id: Identifier) -> Self:
 @final
 @define
 class ShapelessRecipe(Recipe):
-    """Represents a shapeless recipe in the :class:`mcproto.packets.play.UpdateRecipes` packet.
+    """Represents a shapeless recipe in the :class:`~mcproto.packets.play.UpdateRecipes` packet.
 
     Shapeless crafting recipe. Items can be anywhere in the grid.
 
@@ -168,7 +168,7 @@ class ShapelessRecipe(Recipe):
     :param ingredients: The ingredients of the recipe.
     :type ingredients: list[:class:`Ingredient`]
     :param result: The result of the recipe.
-    :type result: :class:`mcproto.types.slot.Slot`
+    :type result: :class:`~mcproto.types.slot.Slot`
     """
 
     recipe_type: ClassVar[int] = 1
@@ -376,9 +376,9 @@ class SmeltingRecipe(Recipe):
     :param category: The category of the recipe. Building = 0, Redstone = 1, Equipment = 2, Misc = 3
     :type category: int
     :param ingredient: The ingredient of the recipe.
-    :type ingredient: :class:`Ingredient
+    :type ingredient: :class:`Ingredient`
     :param result: The result of the recipe.
-    :type result: :class:`mcproto.types.slot.Slot`
+    :type result: :class:`~mcproto.types.slot.Slot`
     :param experience: The experience given when the recipe is completed.
     :type experience: float
     :param cooking_time: The time it takes to complete the recipe.
@@ -465,7 +465,7 @@ class StoneCuttingRecipe(Recipe):
     :param ingredient: The ingredient of the recipe.
     :type ingredient: :class:`Ingredient`
     :param result: The result of the recipe.
-    :type result: :class:`mcproto.types.slot.Slot`
+    :type result: :class:`~mcproto.types.slot.Slot`
     """
 
     recipe_type: ClassVar[int] = 19
@@ -548,7 +548,7 @@ class SmithingTransformRecipe(SmithingTrimRecipe):
     :param addition: The additional ingredient of the recipe.
     :type addition: :class:`Ingredient`
     :param result: The result of the recipe.
-    :type result: :class:`mcproto.types.slot.Slot`
+    :type result: :class:`~mcproto.types.slot.Slot`
     """
 
     recipe_type: ClassVar[int] = 20
diff --git a/mcproto/utils/abc.py b/mcproto/utils/abc.py
@@ -69,6 +69,14 @@ class Serializable(ABC):
 
     Any class that inherits from this class and adds parameters should use the :func:`~mcproto.utils.abc.define`
     decorator.
+
+    Example usage:
+
+    .. literalinclude:: /../tests/mcproto/utils/test_serializable.py
+        :start-after: # region ToyClass
+        :end-before: # endregion
+        :linenos:
+        :language: python
     """
 
     __slots__ = ()
@@ -93,7 +101,7 @@ def serialize(self) -> Buffer:
 
     @abstractmethod
     def serialize_to(self, buf: Buffer, /) -> None:
-        """Write the object to a :class:`~mcproto.Buffer`."""
+        """Write the object to a :class:`~mcproto.buffer.Buffer`."""
         raise NotImplementedError
 
     def validate(self) -> None:
@@ -109,5 +117,5 @@ def validate(self) -> None:
     @classmethod
     @abstractmethod
     def deserialize(cls, buf: Buffer, /) -> Self:
-        """Construct the object from a :class:`~mcproto.Buffer` (transmittable sequence of bytes)."""
+        """Construct the object from a :class:`~mcproto.buffer.Buffer` (transmittable sequence of bytes)."""
         raise NotImplementedError
diff --git a/tests/helpers.py b/tests/helpers.py
@@ -225,10 +225,10 @@ def gen_serializable_test(
     :param cls: The serializable class to test.
     :param fields: A list of tuples containing the field names and types of the serializable class.
     :param serialize_deserialize: A list of tuples containing:
-        - The tuple representing the arguments to pass to the :class:`mcproto.utils.abc.Serializable` class
+        - The tuple representing the arguments to pass to the :class:`~mcproto.utils.abc.Serializable` class
         - The expected bytes
     :param validation_fail: A list of tuples containing the arguments to pass to the
-        :class:`mcproto.utils.abc.Serializable` class and the expected exception, either as is or wrapped in a
+        :class:`~mcproto.utils.abc.Serializable` class and the expected exception, either as is or wrapped in a
         :class:`ExcTest` object.
     :param deserialization_fail: A list of tuples containing the bytes to pass to the :meth:`deserialize` method of the
         class and the expected exception, either as is or wrapped in a :class:`ExcTest` object.
@@ -237,7 +237,8 @@ class and the expected exception, either as is or wrapped in a :class:`ExcTest`
     Example usage:
 
     .. literalinclude:: /../tests/mcproto/utils/test_serializable.py
-        :start-after: # region ToyClass
+        :start-after: # region Test ToyClass
+        :end-before: # endregion
         :linenos:
         :language: python
 
