docs: add hand config documentation (#244)

* docs: add hand config documentation

* address PR comments

Author: Nihisil

.github/wiki/v2-English.md

@@ -16,7 +16,7 @@ It supports optional features like:
 | Disable or enable double yakuman (like suuanko tanki) | `has_double_yakuman` | `True` |
 | Upper limit for cumulative han of non-yakuman yaku (counted yakuman / counted sanbaiman / no limit) | `kazoe_limit` | `HandConstants.KAZOE_LIMITED` |
 | Support kiriage mangan | `kiriage` | `False` |
-| Allow to disable additional +2 fu in open hand (you can make 1-20 hand with that setting) | `fu_for_open_pinfu` | `True` |
+| Whether to add 2 fu for open pinfu-form ron (totaling 30 fu); when disabled, 1 han 20 fu hands become possible | `fu_for_open_pinfu` | `True` |
 | Disable or enable pinfu tsumo | `fu_for_pinfu_tsumo` | `False` |
 | Counting renhou as 5 han or yakuman | `renhou_as_yakuman` | `False` |
 | Disable or enable Daisharin yakuman | `has_daisharin` | `False` |

mahjong/hand_calculating/fu.py

@@ -169,7 +169,7 @@ def calculate_fu(
             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
+            (dragons, seat 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)
         """

mahjong/hand_calculating/hand_config.py

@@ -1,30 +1,80 @@
+"""
+Configuration classes for the hand calculator.
+
+.. rubric:: Classes
+
+* :class:`HandConstants` - constants for kazoe (counted) yakuman limit modes
+* :class:`OptionalRules` - toggle optional rule variants (open tanyao, aka dora, etc.)
+* :class:`HandConfig` - full hand configuration combining win conditions, wind context,
+  bonuses, and optional rules
+"""
+
 from mahjong.constants import EAST
 from mahjong.hand_calculating.yaku_config import YakuConfig
 
 
 class HandConstants:
-    # Hands over 26+ han don't count as double yakuman
+    """Constants for kazoe (counted) yakuman limit modes."""
+
     KAZOE_LIMITED = 0
-    # Hands over 13+ is a sanbaiman
+    """Kazoe hands (13+ han) are capped at single yakuman."""
+
     KAZOE_SANBAIMAN = 1
-    # 26+ han as double yakuman, 39+ han as triple yakuman, etc.
+    """Kazoe hands (13+ han) are capped at sanbaiman."""
+
     KAZOE_NO_LIMIT = 2
+    """No cap on kazoe hands; 13+ han as yakuman, 26+ as double yakuman, and so on."""
 
 
 class OptionalRules:
     """
-    All the supported optional rules
+    Toggle optional rule variants for hand evaluation.
+
+    Japanese mahjong has many rule variations across different parlors and online platforms.
+    This class controls which optional rules are active during hand calculation.
+
+    :ivar has_open_tanyao: allow tanyao on open hands (kuitan)
+    :vartype has_open_tanyao: bool
+    :ivar has_aka_dora: enable red five tiles as bonus dora
+    :vartype has_aka_dora: bool
+    :ivar has_double_yakuman: allow double yakuman scoring for applicable hands
+    :vartype has_double_yakuman: bool
+    :ivar kazoe_limit: kazoe yakuman limit mode; one of
+        :attr:`HandConstants.KAZOE_LIMITED`, :attr:`HandConstants.KAZOE_SANBAIMAN`,
+        or :attr:`HandConstants.KAZOE_NO_LIMIT`
+    :vartype kazoe_limit: int
+    :ivar kiriage: round up to mangan when han/fu are at the boundary (4 han 30 fu or 3 han 60 fu)
+    :vartype kiriage: bool
+    :ivar fu_for_open_pinfu: add 2 fu for open pinfu-form ron (totaling 30 fu);
+        when False, 1 han 20 fu hands become possible
+    :vartype fu_for_open_pinfu: bool
+    :ivar fu_for_pinfu_tsumo: award 2 fu for tsumo on pinfu hands (disabling the 0-fu
+        tsumo pinfu exception)
+    :vartype fu_for_pinfu_tsumo: bool
+    :ivar renhou_as_yakuman: treat renhou as yakuman instead of mangan
+    :vartype renhou_as_yakuman: bool
+    :ivar has_daisharin: enable daisharin 22334455667788p as yakuman;
+        automatically set to True when ``has_daisharin_other_suits`` is True
+    :vartype has_daisharin: bool
+    :ivar has_daisharin_other_suits: allow daisharin in man and sou suits (not only pin)
+    :vartype has_daisharin_other_suits: bool
+    :ivar has_daichisei: enable daichisei (tsuuiisou / all honors as seven pairs) as yakuman
+    :vartype has_daichisei: bool
+    :ivar has_sashikomi_yakuman: enable sashikomi (intentional deal-in for open riichi)
+        as yakuman
+    :vartype has_sashikomi_yakuman: bool
+    :ivar limit_to_sextuple_yakuman: cap yakuman multiplier at 6x
+    :vartype limit_to_sextuple_yakuman: bool
+    :ivar paarenchan_needs_yaku: require at least one yaku for paarenchan to count
+    :vartype paarenchan_needs_yaku: bool
     """
 
     has_open_tanyao: bool
     has_aka_dora: bool
     has_double_yakuman: bool
-    # not implemented! tenhou does not support double yakuman for a single yaku
     kazoe_limit: int
     kiriage: bool
-    # if false, 1-20 hand will be possible
     fu_for_open_pinfu: bool
-    # if true, pinfu tsumo will be disabled
     fu_for_pinfu_tsumo: bool
     renhou_as_yakuman: bool
     has_daisharin: bool
@@ -51,6 +101,31 @@ def __init__(
         paarenchan_needs_yaku: bool = True,
         has_daichisei: bool = False,
     ) -> None:
+        """
+        Initialize optional rules.
+
+        >>> from mahjong.hand_calculating.hand_config import OptionalRules
+        >>> options = OptionalRules(has_open_tanyao=True, kiriage=True)
+        >>> options.has_open_tanyao
+        True
+        >>> options.kiriage
+        True
+
+        :param has_open_tanyao: allow tanyao on open hands (kuitan)
+        :param has_aka_dora: enable red five tiles as bonus dora
+        :param has_double_yakuman: allow double yakuman scoring
+        :param kazoe_limit: kazoe yakuman limit mode
+        :param kiriage: round up to mangan at boundary han/fu combinations
+        :param fu_for_open_pinfu: award 2 fu for open hands with no other fu sources
+        :param fu_for_pinfu_tsumo: award tsumo fu even for pinfu hands
+        :param renhou_as_yakuman: treat renhou as yakuman
+        :param has_daisharin: enable daisharin yakuman
+        :param has_daisharin_other_suits: allow daisharin in all suits
+        :param has_sashikomi_yakuman: enable sashikomi yakuman
+        :param limit_to_sextuple_yakuman: cap yakuman multiplier at 6x
+        :param paarenchan_needs_yaku: require yaku for paarenchan
+        :param has_daichisei: enable daichisei yakuman
+        """
         self.has_open_tanyao = has_open_tanyao
         self.has_aka_dora = has_aka_dora
         self.has_double_yakuman = has_double_yakuman
@@ -69,7 +144,82 @@ def __init__(
 
 class HandConfig(HandConstants):
     """
-    Special class to pass various settings to the hand calculator object
+    Configuration for the hand calculator combining win conditions, wind context, and optional rules.
+
+    Pass a ``HandConfig`` instance to
+    :meth:`~mahjong.hand_calculating.hand.HandCalculator.estimate_hand_value` to describe
+    how the hand was won and which rules apply.
+
+    A default config represents a closed ron with no special conditions:
+
+    >>> from mahjong.hand_calculating.hand_config import HandConfig
+    >>> config = HandConfig()
+    >>> config.is_tsumo
+    False
+    >>> config.is_dealer
+    False
+
+    Configure a dealer tsumo win with riichi and ippatsu:
+
+    >>> from mahjong.constants import EAST
+    >>> config = HandConfig(is_tsumo=True, is_riichi=True, is_ippatsu=True, player_wind=EAST)
+    >>> config.is_tsumo
+    True
+    >>> config.is_dealer
+    True
+
+    Include score bonuses and optional rules:
+
+    >>> from mahjong.hand_calculating.hand_config import OptionalRules
+    >>> options = OptionalRules(has_open_tanyao=True, has_aka_dora=True)
+    >>> config = HandConfig(tsumi_number=2, kyoutaku_number=3, options=options)
+    >>> config.tsumi_number
+    2
+    >>> config.options.has_open_tanyao
+    True
+
+    :ivar yaku: yaku definition objects used during hand evaluation
+    :vartype yaku: ~mahjong.hand_calculating.yaku_config.YakuConfig
+    :ivar options: optional rule settings
+    :vartype options: OptionalRules
+    :ivar is_tsumo: hand won by self-draw
+    :vartype is_tsumo: bool
+    :ivar is_riichi: player declared riichi
+    :vartype is_riichi: bool
+    :ivar is_ippatsu: win within one turn of declaring riichi
+    :vartype is_ippatsu: bool
+    :ivar is_rinshan: win on a replacement tile after calling kan
+    :vartype is_rinshan: bool
+    :ivar is_chankan: win by robbing another player's kan declaration
+    :vartype is_chankan: bool
+    :ivar is_haitei: win on the last drawable tile (tsumo) of the round
+    :vartype is_haitei: bool
+    :ivar is_houtei: win on the discard following the last drawable tile (ron)
+    :vartype is_houtei: bool
+    :ivar is_daburu_riichi: player declared double riichi (riichi on first turn)
+    :vartype is_daburu_riichi: bool
+    :ivar is_nagashi_mangan: all discards are terminals and honors with no calls against them
+    :vartype is_nagashi_mangan: bool
+    :ivar is_tenhou: dealer wins on the initial draw
+    :vartype is_tenhou: bool
+    :ivar is_renhou: non-dealer wins on the first go-around before any calls
+    :vartype is_renhou: bool
+    :ivar is_chiihou: non-dealer wins on the initial draw
+    :vartype is_chiihou: bool
+    :ivar is_open_riichi: player declared open riichi (revealed hand)
+    :vartype is_open_riichi: bool
+    :ivar is_dealer: True when ``player_wind`` is East
+    :vartype is_dealer: bool
+    :ivar player_wind: tile index in 34-format of the player's seat wind, or None
+    :vartype player_wind: int | None
+    :ivar round_wind: tile index in 34-format of the round wind, or None
+    :vartype round_wind: int | None
+    :ivar paarenchan: consecutive dealer wins count; above 0 enables paarenchan yakuman check
+    :vartype paarenchan: int
+    :ivar kyoutaku_number: number of riichi deposits on the table (1000 points each)
+    :vartype kyoutaku_number: int
+    :ivar tsumi_number: number of honba counters (100 points each per counter)
+    :vartype tsumi_number: int
     """
 
     yaku: YakuConfig
@@ -92,11 +242,10 @@ class HandConfig(HandConstants):
     is_dealer: bool
     player_wind: int | None
     round_wind: int | None
-    # for optional yakuman paarenchan above 0 means that dealer has paarenchan possibility
     paarenchan: int
 
-    kyoutaku_number: int  # 1000-point
-    tsumi_number: int  # 100-point
+    kyoutaku_number: int
+    tsumi_number: int
 
     def __init__(
         self,
@@ -120,6 +269,44 @@ def __init__(
         paarenchan: int = 0,
         options: OptionalRules | None = None,
     ) -> None:
+        """
+        Initialize hand configuration.
+
+        >>> from mahjong.hand_calculating.hand_config import HandConfig, OptionalRules
+        >>> from mahjong.constants import EAST, SOUTH
+        >>> config = HandConfig(
+        ...     is_tsumo=True,
+        ...     is_riichi=True,
+        ...     player_wind=EAST,
+        ...     round_wind=SOUTH,
+        ...     options=OptionalRules(has_open_tanyao=True),
+        ... )
+        >>> config.is_dealer
+        True
+        >>> config.round_wind == SOUTH
+        True
+
+        :param is_tsumo: hand won by self-draw
+        :param is_riichi: player declared riichi
+        :param is_ippatsu: win within one turn of declaring riichi
+        :param is_rinshan: win on a replacement tile after calling kan
+        :param is_chankan: win by robbing another player's kan
+        :param is_haitei: win on the last drawable tile
+        :param is_houtei: win on the discard following the last drawable tile
+        :param is_daburu_riichi: player declared double riichi
+        :param is_nagashi_mangan: all discards are terminals and honors
+        :param is_tenhou: dealer wins on the initial draw
+        :param is_renhou: non-dealer wins on the first go-around
+        :param is_chiihou: non-dealer wins on the initial draw
+        :param is_open_riichi: player declared open riichi
+        :param player_wind: tile index in 34-format of the player's seat wind
+        :param round_wind: tile index in 34-format of the round wind
+        :param kyoutaku_number: riichi deposits on the table (1000 points each)
+        :param tsumi_number: honba counters (100 points each per counter)
+        :param paarenchan: consecutive dealer wins count for paarenchan check
+        :param options: optional rule settings; defaults to :class:`OptionalRules` with
+            all defaults when None
+        """
         self.yaku = YakuConfig()
         self.options = options or OptionalRules()
 

mahjong/hand_calculating/scores.py

@@ -59,11 +59,11 @@ def calculate_scores(han: int, fu: int, config: HandConfig, is_yakuman: bool = F
 
         # kazoe hand
         if han >= 13 and not is_yakuman:
-            # Hands over 26+ han don't count as double yakuman
+            # kazoe hands capped at single yakuman
             if config.options.kazoe_limit == HandConfig.KAZOE_LIMITED:
                 han = 13
                 yaku_level = "kazoe yakuman"
-            # Hands over 13+ is a sanbaiman
+            # kazoe hands capped at sanbaiman
             elif config.options.kazoe_limit == HandConfig.KAZOE_SANBAIMAN:
                 han = 12
                 yaku_level = "kazoe sanbaiman"

mahjong/tile.py

@@ -13,7 +13,9 @@ class Tile:
     for consumers that need to track discards with tsumogiri information.
 
     :ivar value: tile index (typically in 136-format)
+    :vartype value: Any
     :ivar is_tsumogiri: True if the tile was discarded immediately after drawing it
+    :vartype is_tsumogiri: Any
     """
 
     value: Any

pyproject.toml

@@ -115,7 +115,6 @@ convention = "pep257"
 
 # temporary
 "./mahjong/hand_calculating/__init__.py" = ["D"]
-"./mahjong/hand_calculating/hand_config.py" = ["D"]
 "./mahjong/hand_calculating/hand_response.py" = ["D"]
 "./mahjong/hand_calculating/hand.py" = ["D"]
 "./mahjong/hand_calculating/scores.py" = ["D"]