mahjong 2.0.0.dev1__py3-none-any.whl → 2.0.0.dev2__py3-none-any.whl

mahjong/__init__.py

@@ -0,0 +1,87 @@
+"""
+_summary_.
+
+Tile representation
+###################
+
+mpsz-notation
+-------------
+
+The *mpsz-notation* is the same format used by the Tenhou (see https://tenhou.net/2/), where each tile is
+represented by a two-character string: a digit for the rank followed by a letter for the suit.
+
+The suit letters correspond to:
+
+* `m` - manzu (萬子, characters)
+* `p` - pinzu (筒子, circles)
+* `s` - souzu (索子, bamboo)
+* `z` - jihai (字牌, honors)
+
+Within the numbered suits (`m`, `p`, `s`), ranks run from `1` through `9`; the red fives are
+written with rank `0` (e.g., `0m`, `0p`, `0s`).
+
+Honors (`z`) use ranks to distinguish individual tiles:
+
+* `1` - East (東)
+* `2` - South (南)
+* `3` - West (西)
+* `4` - North (北)
+* `5` - White dragon (白, haku)
+* `6` - Green dragon (發, hatsu)
+* `7` - Red dragon (中, chun)
+
+Multiple tiles may be concatenated without separators to form a string that represents a collection. For example:
+
+``123m406p789s11555z``
+
+is equivalent to ``1m2m3m4p0p6p7s8s9s1z1z5z5z5z``.
+
+34-format
+---------
+
+In the *34-format*, an entry is assigned to each of the 34 tile types.
+It does **not** distinguish a red five from a normal five - both map to the same entry.
+The format is commonly used in two ways:
+
+* A sequence of length 34 where each entry represents the count of the corresponding tile type.
+* A list of tile-type indices, containing one element per tile rather than counts.
+  For example, a pon of 1m is represented as ``[0, 0, 0]``.
+
+The correspondence between the index and the tile is shown in the table below.
+
++-------+----+----+----+----+----+----+----+----+----+
+| Index | 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8  |
++-------+----+----+----+----+----+----+----+----+----+
+| Tile  | 1m | 2m | 3m | 4m | 5m | 6m | 7m | 8m | 9m |
++-------+----+----+----+----+----+----+----+----+----+
+
++-------+----+----+----+----+----+----+----+----+----+
+| Index | 9  | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 |
++-------+----+----+----+----+----+----+----+----+----+
+| Tile  | 1p | 2p | 3p | 4p | 5p | 6p | 7p | 8p | 9p |
++-------+----+----+----+----+----+----+----+----+----+
+
++-------+----+----+----+----+----+----+----+----+----+
+| Index | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
++-------+----+----+----+----+----+----+----+----+----+
+| Tile  | 1s | 2s | 3s | 4s | 5s | 6s | 7s | 8s | 9s |
++-------+----+----+----+----+----+----+----+----+----+
+
++-------+-----------+------------+-----------+------------+------------+------------+----------+
+| Index | 27        | 28         | 29        | 30         | 31         | 32         | 33       |
++-------+-----------+------------+-----------+------------+------------+------------+----------+
+| Tile  | East (1z) | South (2z) | West (3z) | North (4z) | White (5z) | Green (6z) | Red (7z) |
++-------+-----------+------------+-----------+------------+------------+------------+----------+
+
+136-format
+----------
+
+In the *136-format*, each physical tile (four copies of each of the 34 tile types) is assigned a unique integer.
+It is primarily used when treating tiles as individual objects rather than counts, such as melds.
+
+The integers range from 0 to 135.
+IDs are assigned in groups of four: the four copies of 1m receive `0`, `1`, `2`, and `3`;
+the four copies of 2m receive `4`, `5`, `6`, and `7`;
+and so on, up to the four copies of red dragon (7z), which receive `132`, `133`, `134`, and `135`.
+Red fives are assigned the indices `16` (`0m`), `52` (`0p`), and `88` (`0s`).
+"""

mahjong/agari.py

@@ -2,13 +2,37 @@ from collections.abc import Collection, Sequence
 
 
 class Agari:
+    """Agari (winning hand) detection."""
+
     @staticmethod
     def is_agari(tiles_34: Sequence[int], open_sets_34: Collection[Sequence[int]] | None = None) -> bool:
         """
-        Determine whether the hand is a winning hand (agari)
-        :param tiles_34: 34 tiles format array
-        :param open_sets_34: array of arrays of 34 tiles format
-        :return: boolean
+        Determine whether the given tiles form a complete hand structure.
+
+        Validate the tile arrangement only (4 melds + 1 pair, seven pairs, or thirteen orphans),
+        not yaku or scoring. When open sets are provided, the declared meld tiles are subtracted
+        before checking.
+
+        The concealed portion can be passed alone without melds, which is valid
+        for any number of melds (0-4) plus 1 pair:
+
+        0 melds + 1 pair (valid hand):
+
+        >>> tiles_34 = [0] * 34
+        >>> tiles_34[0] = 2
+        >>> Agari.is_agari(tiles_34)
+        True
+
+        1 meld (triplet) without a pair is not a valid hand:
+
+        >>> tiles_34 = [0] * 34
+        >>> tiles_34[0] = 3
+        >>> Agari.is_agari(tiles_34)
+        False
+
+        :param tiles_34: hand in 34-format count array (length 34)
+        :param open_sets_34: declared melds as arrays of tile indices in 34-format
+        :return: True if the hand is complete
         """
         if open_sets_34:
             # subtract declared meld tiles so the algorithm checks only the closed portion

mahjong/constants.py

@@ -1,24 +1,50 @@
-# 1 and 9
 TERMINAL_INDICES = frozenset([0, 8, 9, 17, 18, 26])
+"""Tile indices (34-format) of terminal tiles — 1 and 9 of each suit (man, pin, sou)."""
 
-# dragons and winds
 EAST = 27
+"""Tile index (34-format) for East wind."""
+
 SOUTH = 28
+"""Tile index (34-format) for South wind."""
+
 WEST = 29
+"""Tile index (34-format) for West wind."""
+
 NORTH = 30
+"""Tile index (34-format) for North wind."""
+
 HAKU = 31
+"""Tile index (34-format) for Haku (white dragon)."""
+
 HATSU = 32
+"""Tile index (34-format) for Hatsu (green dragon)."""
+
 CHUN = 33
+"""Tile index (34-format) for Chun (red dragon)."""
 
 WINDS = frozenset([EAST, SOUTH, WEST, NORTH])
+"""Tile indices (34-format) of all four wind tiles."""
+
 DRAGONS = frozenset([HAKU, HATSU, CHUN])
+"""Tile indices (34-format) of all three dragon tiles."""
+
 HONOR_INDICES = WINDS | DRAGONS
+"""Tile indices (34-format) of all honor tiles — winds and dragons."""
+
 TERMINAL_AND_HONOR_INDICES = TERMINAL_INDICES | HONOR_INDICES
+"""Tile indices (34-format) of all terminal and honor tiles."""
 
 FIVE_RED_MAN = 16
+"""Tile index (136-format) for the red five of man (characters)."""
+
 FIVE_RED_PIN = 52
+"""Tile index (136-format) for the red five of pin (circles)."""
+
 FIVE_RED_SOU = 88
+"""Tile index (136-format) for the red five of sou (bamboo)."""
 
 AKA_DORAS = frozenset([FIVE_RED_MAN, FIVE_RED_PIN, FIVE_RED_SOU])
+"""Tile indices (136-format) of all three red five (aka dora) tiles."""
 
 DISPLAY_WINDS = {EAST: "East", SOUTH: "South", WEST: "West", NORTH: "North"}
+"""Mapping from wind tile indices (34-format) to their English display names."""

mahjong/hand_calculating/divider.py

@@ -50,16 +50,81 @@ _Blocks = tuple[_Block, ...]
 
 
 class HandDivider:
+    """
+    Decompose a winning hand into all possible block combinations.
+
+    A valid combination consists of 4 melds (sequences, triplets, or quads) plus 1 pair.
+    Chiitoitsu (seven pairs) is also recognized when no melds are declared.
+    Multiple valid decompositions may exist for the same hand.
+
+    Each decomposition is a list of blocks, where each block is a list of tile indices
+    in 34-format:
+
+    - pair: ``[tile, tile]`` (length 2, identical tiles)
+    - triplet: ``[tile, tile, tile]`` (length 3, identical tiles)
+    - sequence: ``[tile, tile+1, tile+2]`` (length 3, consecutive tiles)
+    - quad: ``[tile, tile, tile, tile]`` (length 4, identical tiles)
+    """
+
     @staticmethod
     def divide_hand(
         tiles_34: Sequence[int],
         melds: Collection[Meld] | None = None,
     ) -> list[list[list[int]]]:
         """
-        Return a list of possible hands.
-        :param tiles_34:
-        :param melds: list of Meld objects
-        :return:
+        Return all valid decompositions of the hand into blocks.
+
+        Decompose the full hand (including any declared melds) into every possible
+        combination of 4 melds + 1 pair, or 7 pairs (chiitoitsu, only when no melds
+        are declared).
+
+        Single decomposition (one triplet, three sequences, and a pair):
+
+        >>> from mahjong.hand_calculating.divider import HandDivider
+        >>> from mahjong.tile import TilesConverter
+        >>> tiles_34 = TilesConverter.one_line_string_to_34_array("234567m23455s777z")
+        >>> result = HandDivider.divide_hand(tiles_34)
+        >>> result
+        [[[1, 2, 3], [4, 5, 6], [19, 20, 21], [22, 22], [33, 33, 33]]]
+
+        Multiple decompositions (triplets vs. sequences):
+
+        >>> tiles_34 = TilesConverter.one_line_string_to_34_array("11122233388899m")
+        >>> result = HandDivider.divide_hand(tiles_34)
+        >>> result
+        [[[0, 0, 0], [1, 1, 1], [2, 2, 2], [7, 7, 7], [8, 8]], [[0, 1, 2], [0, 1, 2], [0, 1, 2], [7, 7, 7], [8, 8]]]
+
+        Ryanpeikou form (decomposes into both 4 melds + 1 pair and chiitoitsu):
+
+        >>> tiles_34 = TilesConverter.one_line_string_to_34_array("11223344556677m")
+        >>> result = HandDivider.divide_hand(tiles_34)
+        >>> len(result)
+        4
+        >>> [[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6]] in result
+        True
+        >>> [[0, 1, 2], [0, 1, 2], [3, 4, 5], [3, 4, 5], [6, 6]] in result
+        True
+
+        Hands with declared melds:
+
+        >>> from mahjong.meld import Meld
+        >>> tiles_34 = TilesConverter.string_to_34_array(pin="234777888999", honors="22")
+        >>> chi_1 = Meld(meld_type=Meld.CHI, tiles=TilesConverter.string_to_136_array(pin="789"))
+        >>> chi_2 = Meld(meld_type=Meld.CHI, tiles=TilesConverter.string_to_136_array(pin="234"))
+        >>> result = HandDivider.divide_hand(tiles_34, [chi_1, chi_2])
+        >>> result
+        [[[10, 11, 12], [15, 16, 17], [15, 16, 17], [15, 16, 17], [28, 28]]]
+
+        Invalid hands return an empty list:
+
+        >>> HandDivider.divide_hand([5] * 34)
+        []
+
+        :param tiles_34: hand in 34-format count array (length 34), including tiles from melds
+        :param melds: declared melds (:class:`~mahjong.meld.Meld` objects); their tiles are
+            subtracted from ``tiles_34`` before decomposing the concealed portion
+        :return: list of decompositions, where each decomposition is a list of blocks
+            (each block is a list of tile indices in 34-format)
         """
         if not HandDivider._validate_tiles(tiles_34):
             return []

mahjong/hand_calculating/fu.py

@@ -7,6 +7,16 @@ from mahjong.meld import Meld
 
 
 class FuDetail(TypedDict):
+    """
+    A single fu component with its point value and reason.
+
+    Each entry in the fu breakdown returned by :meth:`FuCalculator.calculate_fu`
+    describes one source of fu (e.g., base fu, a closed pon, or a wait type).
+
+    :param fu: fu points awarded for this component
+    :param reason: identifier string matching one of the :class:`FuCalculator` reason constants
+    """
+
     fu: int
     reason: str
 
@@ -20,26 +30,61 @@ _IS_KAN = 2
 
 
 class FuCalculator:
+    """
+    Calculate fu (minipoints) for a winning hand decomposition.
+
+    Fu are computed from the hand's meld structure, wait type, pair, and winning method.
+    The result is a detailed breakdown of fu components and the total fu rounded up to
+    the nearest 10.
+    """
+
     BASE = "base"
+    """Base fu: 20 for open/tsumo, 30 for closed ron, 25 for chiitoitsu."""
+
     PENCHAN = "penchan"
+    """Penchan (edge wait): 2 fu for completing 1-2-3 with the 3, or 7-8-9 with the 7."""
+
     KANCHAN = "kanchan"
+    """Kanchan (closed wait): 2 fu for waiting on the middle tile of a sequence."""
+
     VALUED_PAIR = "valued_pair"
+    """Valued pair: 2 fu for a pair of dragon, seat wind, or round wind tiles."""
+
     DOUBLE_VALUED_PAIR = "double_valued_pair"
+    """Double valued pair: 4 fu when the pair tile is both seat wind and round wind."""
+
     PAIR_WAIT = "pair_wait"
+    """Pair wait: 2 fu for winning on the pair tile."""
+
     TSUMO = "tsumo"
+    """Tsumo: 2 fu for winning by self-draw."""
+
     HAND_WITHOUT_FU = "hand_without_fu"
+    """Open pinfu: 2 fu for an open hand with no other fu sources."""
 
     CLOSED_PON = "closed_pon"
+    """Closed pon of simple tiles: 4 fu."""
+
     OPEN_PON = "open_pon"
+    """Open pon of simple tiles: 2 fu."""
 
     CLOSED_TERMINAL_PON = "closed_terminal_pon"
+    """Closed pon of terminal or honor tiles: 8 fu."""
+
     OPEN_TERMINAL_PON = "open_terminal_pon"
+    """Open pon of terminal or honor tiles: 4 fu."""
 
     CLOSED_KAN = "closed_kan"
+    """Closed kan of simple tiles: 16 fu."""
+
     OPEN_KAN = "open_kan"
+    """Open kan of simple tiles: 8 fu."""
 
     CLOSED_TERMINAL_KAN = "closed_terminal_kan"
+    """Closed kan of terminal or honor tiles: 32 fu."""
+
     OPEN_TERMINAL_KAN = "open_terminal_kan"
+    """Open kan of terminal or honor tiles: 16 fu."""
 
     # lookup table indexed by [is_terminal_or_honor][is_kan][is_open] -> (fu, reason)
     _PON_KAN_FU_TABLE = (
@@ -63,14 +108,70 @@ class FuCalculator:
         melds: Collection[Meld] | None = None,
     ) -> tuple[list[FuDetail], int]:
         """
-        Calculate hand fu with explanations
-        :param hand:
-        :param win_tile: 136 tile format
-        :param win_group: one set where win tile exists
-        :param config: HandConfig object
-        :param valued_tiles: dragons, player wind, round wind
-        :param melds: opened sets
-        :return:
+        Calculate fu for a winning hand decomposition.
+
+        Analyze the hand's meld structure, wait type, pair, and winning method to produce
+        a detailed breakdown of fu components and the total fu rounded up to the nearest 10.
+
+        Chiitoitsu (seven pairs) always receives 25 fu:
+
+        >>> from mahjong.hand_calculating.fu import FuCalculator
+        >>> from mahjong.hand_calculating.hand_config import HandConfig
+        >>> hand = [[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6]]
+        >>> win_tile = 24
+        >>> win_group = [6, 6]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig())
+        >>> fu
+        25
+
+        A closed ron hand with only chi melds and a non-valued pair (pinfu) receives 30 fu:
+
+        >>> hand = [[0, 1, 2], [3, 4, 5], [9, 10, 11], [18, 19, 20], [27, 27]]
+        >>> win_tile = 20
+        >>> win_group = [3, 4, 5]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig())
+        >>> fu
+        30
+
+        A closed pon of simple tiles adds 4 fu:
+
+        >>> hand = [[2, 2, 2], [3, 4, 5], [9, 10, 11], [18, 19, 20], [27, 27]]
+        >>> win_tile = 20
+        >>> win_group = [3, 4, 5]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig())
+        >>> fu
+        40
+        >>> {"fu": 4, "reason": FuCalculator.CLOSED_PON} in fu_details
+        True
+
+        A double valued pair with an open terminal pon:
+
+        >>> from mahjong.meld import Meld
+        >>> hand = [[2, 3, 4], [9, 10, 11], [18, 19, 20], [33, 33, 33], [27, 27]]
+        >>> win_tile = 8
+        >>> win_group = [2, 3, 4]
+        >>> valued_tiles = [27, 27]
+        >>> melds = [Meld(meld_type=Meld.PON, tiles=[132, 133, 134], opened=True)]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig(), valued_tiles, melds)
+        >>> fu
+        30
+        >>> {"fu": 4, "reason": FuCalculator.DOUBLE_VALUED_PAIR} in fu_details
+        True
+        >>> {"fu": 4, "reason": FuCalculator.OPEN_TERMINAL_PON} in fu_details
+        True
+
+        :param hand: decomposed hand as a collection of tile sets, each a sequence of tile
+            indices in 34-format: a pair (length 2), chi (length 3 with consecutive tiles),
+            pon (length 3 with identical tiles), or kan (length 4);
+            chiitoitsu hands have 7 pairs
+        :param win_tile: the winning tile index in 136-format
+        :param win_group: the tile set (from ``hand``) that contains the winning tile,
+            as tile indices in 34-format
+        :param config: hand configuration with win method and optional rule settings
+        :param valued_tiles: tile indices in 34-format for tiles that grant pair fu
+            (dragons, player wind, round wind); pass the same index twice for double-valued
+        :param melds: declared melds (chi, pon, kan)
+        :return: tuple of (fu component list, total fu rounded up to nearest 10)
         """
         # chiitoitsu: always 25 fu
         if len(hand) == 7:

mahjong/hand_calculating/hand.py

@@ -424,7 +424,7 @@ class HandCalculator:
                     if not is_aotenjou:
                         hand_yaku = yakuman_list
                     else:
-                        scores_calculator.aotenjou_filter_yaku(hand_yaku, config)
+                        scores_calculator.aotenjou_filter_yaku(hand_yaku, config)  # ty: ignore[unresolved-attribute]
                         yakuman_list = []
 
                 # calculate han

mahjong/hand_calculating/yaku_list/__init__.py

@@ -41,3 +41,49 @@ from mahjong.hand_calculating.yaku_list.tanyao import Tanyao
 from mahjong.hand_calculating.yaku_list.toitoi import Toitoi
 from mahjong.hand_calculating.yaku_list.tsumo import Tsumo
 from mahjong.hand_calculating.yaku_list.ura_dora import UraDora
+
+__all__ = [
+    "AkaDora",
+    "Chankan",
+    "Chantai",
+    "Chiitoitsu",
+    "Chinitsu",
+    "Chun",
+    "DaburuOpenRiichi",
+    "DaburuRiichi",
+    "Dora",
+    "Haitei",
+    "Haku",
+    "Hatsu",
+    "Honitsu",
+    "Honroto",
+    "Houtei",
+    "Iipeiko",
+    "Ippatsu",
+    "Ittsu",
+    "Junchan",
+    "NagashiMangan",
+    "OpenRiichi",
+    "Pinfu",
+    "Renhou",
+    "Riichi",
+    "Rinshan",
+    "RoundWindEast",
+    "RoundWindNorth",
+    "RoundWindSouth",
+    "RoundWindWest",
+    "Ryanpeikou",
+    "SanKantsu",
+    "Sanankou",
+    "Sanshoku",
+    "SanshokuDoukou",
+    "SeatWindEast",
+    "SeatWindNorth",
+    "SeatWindSouth",
+    "SeatWindWest",
+    "Shosangen",
+    "Tanyao",
+    "Toitoi",
+    "Tsumo",
+    "UraDora",
+]

mahjong/hand_calculating/yaku_list/yakuman/__init__.py

@@ -18,3 +18,26 @@ from mahjong.hand_calculating.yaku_list.yakuman.suuankou_tanki import SuuankouTa
 from mahjong.hand_calculating.yaku_list.yakuman.suukantsu import Suukantsu
 from mahjong.hand_calculating.yaku_list.yakuman.tenhou import Tenhou
 from mahjong.hand_calculating.yaku_list.yakuman.tsuisou import Tsuuiisou
+
+__all__ = [
+    "Chiihou",
+    "Chinroutou",
+    "ChuurenPoutou",
+    "DaburuChuurenPoutou",
+    "DaburuKokushiMusou",
+    "DaiSuushii",
+    "Daichisei",
+    "Daisangen",
+    "Daisharin",
+    "KokushiMusou",
+    "Paarenchan",
+    "RenhouYakuman",
+    "Ryuuiisou",
+    "Sashikomi",
+    "Shousuushii",
+    "Suuankou",
+    "SuuankouTanki",
+    "Suukantsu",
+    "Tenhou",
+    "Tsuuiisou",
+]

mahjong/meld.py

@@ -5,15 +5,68 @@ from mahjong.tile import TilesConverter
 
 
 class Meld:
+    """
+    Representation of a declared meld (called or concealed tile group).
+
+    A meld is a set of tiles that a player has declared, either by calling another
+    player's discard (open meld) or by declaring a concealed kan. Meld types follow
+    standard Japanese mahjong terminology:
+
+    - **Chi** — a sequence of three consecutive suited tiles, called from the player to the left.
+    - **Pon** — a triplet of identical tiles, called from any player.
+    - **Kan** — a quad of identical tiles (open, closed, or extended).
+    - **Shouminkan** — an added kan (extending an existing pon with the fourth tile).
+    - **Nuki** — a special declaration used in three-player mahjong (north wind extraction).
+
+    Create an open chi meld:
+
+    >>> from mahjong.meld import Meld
+    >>> from mahjong.tile import TilesConverter
+    >>> tiles = TilesConverter.string_to_136_array(man="123")
+    >>> meld = Meld(meld_type=Meld.CHI, tiles=tiles)
+    >>> meld.type
+    'chi'
+    >>> meld.tiles
+    (0, 4, 8)
+
+    Create a closed kan:
+
+    >>> tiles = TilesConverter.string_to_136_array(man="1111")
+    >>> meld = Meld(meld_type=Meld.KAN, tiles=tiles, opened=False)
+    >>> meld.opened
+    False
+
+    :ivar type: one of the meld type constants (CHI, PON, KAN, SHOUMINKAN, NUKI)
+    :vartype type: str | None
+    :ivar tiles: tile indices in 136-format, stored as an immutable tuple
+    :vartype tiles: tuple[int, ...]
+    :ivar opened: True for open melds (called from another player), False for closed kan
+    :vartype opened: bool
+    :ivar called_tile: the specific tile index (136-format) that was called to form this meld
+    :vartype called_tile: int | None
+    :ivar who: seat index (0-3) of the player who declared the meld
+    :vartype who: int | None
+    :ivar from_who: seat index (0-3) of the player who discarded the called tile
+    :vartype from_who: int | None
+    """
+
     CHI = "chi"
+    """Chi (sequence) meld type — three consecutive suited tiles."""
+
     PON = "pon"
+    """Pon (triplet) meld type — three identical tiles."""
+
     KAN = "kan"
+    """Kan (quad) meld type — four identical tiles."""
+
     SHOUMINKAN = "shouminkan"
+    """Shouminkan (added kan) meld type — extending a pon with the fourth tile."""
+
     NUKI = "nuki"
+    """Nuki (north wind extraction) meld type, at the moment is not used in the library."""
 
     type: str | None
     tiles: tuple[int, ...]
-    # we need it to distinguish opened and closed kan
     opened: bool
     called_tile: int | None
     who: int | None
@@ -28,6 +81,25 @@ class Meld:
         who: int | None = None,
         from_who: int | None = None,
     ) -> None:
+        """
+        Initialize a meld.
+
+        >>> from mahjong.meld import Meld
+        >>> from mahjong.tile import TilesConverter
+        >>> tiles = TilesConverter.string_to_136_array(man="111")
+        >>> meld = Meld(meld_type=Meld.PON, tiles=tiles, who=0, from_who=2)
+        >>> meld.type
+        'pon'
+        >>> meld.who
+        0
+
+        :param meld_type: one of the meld type constants (CHI, PON, KAN, SHOUMINKAN, NUKI)
+        :param tiles: tile indices in 136-format
+        :param opened: True for open melds (called from another player), False for closed kan
+        :param called_tile: the specific tile index (136-format) that was called to form this meld
+        :param who: seat index (0-3) of the player who declared the meld
+        :param from_who: seat index (0-3) of the player who discarded the called tile
+        """
         self.type = meld_type
         self.tiles = tuple(tiles) if tiles else ()
         self.opened = opened
@@ -36,17 +108,40 @@ class Meld:
         self.from_who = from_who
 
     def __setattr__(self, name: str, value: object) -> None:
+        """Invalidate the tiles_34 cache when tiles are reassigned."""
         super().__setattr__(name, value)
         if name == "tiles" and "tiles_34" in self.__dict__:
             del self.__dict__["tiles_34"]
 
     def __str__(self) -> str:
+        """
+        Return a human-readable string with meld type and tiles.
+
+        >>> from mahjong.meld import Meld
+        >>> from mahjong.tile import TilesConverter
+        >>> tiles = TilesConverter.string_to_136_array(man="123")
+        >>> meld = Meld(meld_type=Meld.CHI, tiles=tiles)
+        >>> str(meld)
+        'Type: chi, Tiles: 123m (0, 4, 8)'
+        """
         return f"Type: {self.type}, Tiles: {TilesConverter.to_one_line_string(self.tiles)} {self.tiles}"
 
-    # for calls in array
     def __repr__(self) -> str:
+        """Return the same representation as __str__."""
         return self.__str__()
 
     @cached_property
     def tiles_34(self) -> list[int]:
+        """
+        Convert the meld's 136-format tile indices to 34-format tile indices.
+
+        >>> from mahjong.meld import Meld
+        >>> from mahjong.tile import TilesConverter
+        >>> tiles = TilesConverter.string_to_136_array(man="111")
+        >>> meld = Meld(meld_type=Meld.PON, tiles=tiles)
+        >>> meld.tiles_34
+        [0, 0, 0]
+
+        :return: list of tile indices in 34-format
+        """
         return [x // 4 for x in self.tiles]