📝 Add docstrings to dev

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

tests/test_jmcomic/test_jm_client.py

@@ -39,13 +39,23 @@ 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,
             '530595'
         )
 
     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))