docs: Add Google-style docstrings to token_id.py (#636)

Signed-off-by: Pranay <[email protected]>

Author: Pranay22077

CHANGELOG.md

@@ -7,6 +7,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 ## [Unreleased]
 
 ### Added
+- docs: Add Google-style docstrings to `TokenId` class and its methods in `token_id.py`.
 - Standardized docstrings, improved error handling, and updated type hinting (`str | None` to `Optional[str]`) for the `FileId` class (#652).
 
 - Add Google-style docstrings to `AccountInfo` class and its methods in `account_info.py`.

src/hiero_sdk_python/tokens/token_id.py

@@ -19,13 +19,31 @@
 
 @dataclass(frozen=True, eq=True, init=True, repr=True)
 class TokenId:
-    """Immutable token identifier (shard, realm, num) with validation and protobuf conversion."""
+    """Represents an immutable Hedera token identifier (shard, realm, num).
+
+    This is a frozen dataclass providing validation, string parsing,
+    and protobuf conversion utilities for a token ID.
+
+    Attributes:
+        shard (int): The shard number (non-negative).
+        realm (int): The realm number (non-negative).
+        num (int): The entity number (non-negative).
+        checksum (str | None): An optional checksum, automatically populated
+            when parsing from a string with a checksum. Not directly
+            initializable.
+    """
     shard: int
     realm: int
     num: int
     checksum: str | None = field(default=None, init=False)
 
     def __post_init__(self) -> None:
+        """
+        Validates that shard, realm, and num are non-negative after initialization.
+
+        Raises:
+            ValueError: If shard, realm, or num is less than 0.
+        """
         if self.shard < 0:
             raise ValueError('Shard must be >= 0')
         if self.realm < 0:
@@ -35,8 +53,17 @@ def __post_init__(self) -> None:
 
     @classmethod
     def _from_proto(cls, token_id_proto: Optional[basic_types_pb2.TokenID] = None) -> "TokenId":
-        """
-        Creates a TokenId instance from a protobuf TokenID object.
+        """Creates a TokenId instance from a protobuf TokenID object.
+
+        Args:
+            token_id_proto (Optional[basic_types_pb2.TokenID]): The protobuf
+                TokenID object.
+
+        Returns:
+            TokenId: The corresponding TokenId instance.
+
+        Raises:
+            ValueError: If token_id_proto is None.
         """
         if token_id_proto is None:
             raise ValueError('TokenId is required')
@@ -48,8 +75,10 @@ def _from_proto(cls, token_id_proto: Optional[basic_types_pb2.TokenID] = None) -
         )
 
     def _to_proto(self) -> basic_types_pb2.TokenID:
-        """
-        Converts the TokenId instance to a protobuf TokenID object.
+        """Converts the TokenId instance to a protobuf TokenID object.
+
+        Returns:
+            basic_types_pb2.TokenID: The corresponding protobuf TokenID object.
         """
         token_id_proto = basic_types_pb2.TokenID()
         token_id_proto.shardNum = self.shard
@@ -59,19 +88,20 @@ def _to_proto(self) -> basic_types_pb2.TokenID:
 
     @classmethod
     def from_string(cls, token_id_str: Optional[str] = None) -> "TokenId":
-        """
-        Creates a TokenId instance from a string in the format 'shard.realm.num'.
+        """Parses a string to create a TokenId instance.
+
+        The string can be in the format 'shard.realm.num' or
+        'shard.realm.num-checksum'.
 
         Args:
-            token_id_str (str): The string representation of the token ID.
+            token_id_str (Optional[str]): The token ID string to parse.
 
         Returns:
-            TokenId: A new TokenId instance parsed from the provided string.
+            TokenId: The corresponding TokenId instance.
 
         Raises:
-            ValueError: 
-                - If token_id_str is None.
-                - If the input string cannot be parsed or is malformed.
+            ValueError: If the token_id_str is None, empty, or in an
+                invalid format.
         """
         if token_id_str is None:
             raise ValueError("token_id_str cannot be None") 
@@ -92,7 +122,19 @@ def from_string(cls, token_id_str: Optional[str] = None) -> "TokenId":
             )from e
 
     def validate_checksum(self, client: Client) -> None:
-        """Validate the checksum for the TokenId instance"""
+        """Validates the checksum (if present) against the client's network.
+
+        Args:
+            client (Client): The client instance, used to determine the
+                network ledger ID for validation.
+
+        Raises:
+            ValueError: If the client's ledger ID is not set (required for
+                validation).
+            ValueError: If the checksum is present but does not match the
+                expected checksum for the client's network (e.g.,
+                "Checksum mismatch for 0.0.123").
+        """
         validate_checksum(
             shard=self.shard,
             realm=self.realm,
@@ -102,9 +144,17 @@ def validate_checksum(self, client: Client) -> None:
         )
 
     def to_string_with_checksum(self, client:Client) -> str:
-        """
-        Returns the string representation of the TokenId with checksum 
-        in the format 'shard.realm.num-checksum'
+        """Returns the string representation with a network-specific checksum.
+
+        Generates a checksum based on the client's network and returns
+        the ID in 'shard.realm.num-checksum' format.
+
+        Args:
+            client (Client): The client instance used to generate the
+                network-specific checksum.
+
+        Returns:
+            str: The token ID string with a calculated checksum.
         """
         return format_to_string_with_checksum(
             shard=self.shard,
@@ -114,11 +164,17 @@ def to_string_with_checksum(self, client:Client) -> str:
         )
 
     def __str__(self) -> str:
-        """
-        Returns the string representation of the TokenId in the format 'shard.realm.num'.
+        """Returns the simple string representation 'shard.realm.num'.
+
+        Returns:
+            str: The token ID string in 'shard.realm.num' format.
         """
         return format_to_string(self.shard, self.realm, self.num)
 
     def __hash__(self) -> int:
-        """ Returns a hash of the TokenId instance. """
+        """Generates a hash based on the shard, realm, and num.
+
+        Returns:
+            int: A hash of the TokenId instance.
+        """
         return hash((self.shard, self.realm, self.num))