From 982dce51763e07642c813af1225df8ba4ac938e3 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Tue, 3 Feb 2026 12:20:52 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`dev`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @hect0x7.

* https://github.com/hect0x7/JMComic-Crawler-Python/pull/512#issuecomment-3840257020

The following files were modified:

* `src/jmcomic/jm_client_impl.py`
* `tests/test_jmcomic/test_jm_client.py`
---
 src/jmcomic/jm_client_impl.py        | 14 ++++++++++++--
 tests/test_jmcomic/test_jm_client.py | 15 +++++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/jmcomic/jm_client_impl.py b/src/jmcomic/jm_client_impl.py
index 730378c96..bf0b5a500 100644
--- a/src/jmcomic/jm_client_impl.py
+++ b/src/jmcomic/jm_client_impl.py
@@ -699,7 +699,17 @@ def get_scramble_id(self, photo_id, album_id=None):
 
     def fetch_detail_entity(self, jmid, clazz):
         """
-        请求实体类
+        Fetches a JM entity (album or chapter) by its JM ID and returns it as an instance of `clazz`.
+        
+        Parameters:
+            jmid (str | int): JM ID or value parseable to a JM ID.
+            clazz (type): Entity class to parse the response into (e.g., `JmAlbumDetail` or a chapter/detail class).
+        
+        Returns:
+            object: An instance of `clazz` populated from the API response data.
+        
+        Raises:
+            Exception: Raised via ExceptionTool.raise_missing if the API response lacks required data.
         """
         jmid = JmcomicText.parse_to_jm_id(jmid)
         url = self.API_ALBUM if issubclass(clazz, JmAlbumDetail) else self.API_CHAPTER
@@ -1195,4 +1205,4 @@ def get_photo_detail(self, photo_id, fetch_album=True, fetch_scramble_id=True) -
         if scramble_id != '':
             photo.scramble_id = scramble_id
 
-        return photo
+        return photo
\ No newline at end of file
diff --git a/tests/test_jmcomic/test_jm_client.py b/tests/test_jmcomic/test_jm_client.py
index fec18554c..3ddf6574d 100644
--- a/tests/test_jmcomic/test_jm_client.py
+++ b/tests/test_jmcomic/test_jm_client.py
@@ -39,6 +39,11 @@ def test_gt_300_photo(self):
         self.client.download_by_image_detail(image, self.option.decide_image_filepath(image))
 
     def test_album_missing(self):
+        """
+        Verify get_album_detail raises MissingAlbumPhotoException for a missing album.
+        
+        Asserts that requesting album with ID '530595' causes a MissingAlbumPhotoException to be raised.
+        """
         self.assertRaises(
             MissingAlbumPhotoException,
             self.client.get_album_detail,
@@ -46,6 +51,11 @@ def test_album_missing(self):
         )
 
     def test_detail_property_list(self):
+        """
+        Validate that selected property lists of album 410090 match expected values after conversion to Chinese.
+        
+        Fetches album detail for ID 410090 and compares the first up to nine entries of its `works`, `actors`, `tags`, and `authors` lists against expected values, converting both sides with `JmcomicText.to_zh_cn` before asserting element-wise equality.
+        """
         album = self.client.get_album_detail(410090)
 
         ans = [
@@ -339,4 +349,9 @@ def test_download_cover(self):
         self.client.download_album_cover(album_id, f'{self.option.dir_rule.base_dir}/{album_id}_3x4.webp', '_3x4')
 
     def test_ranking(self):
+        """
+        Fetches and prints the client's monthly ranking for month 1.
+        
+        This test retrieves the month-1 ranking from the configured client and writes it to standard output.
+        """
         print(self.client.month_ranking(1))
\ No newline at end of file