📝 Add docstrings to fix_gitlab_new_mr

gitlab_integration/gitlab_fetcher.py

@@ -111,8 +111,11 @@ def __init__(self, project_id, branch_name = ""):
 
     def get_info(self):
         """
-        Get the project information
-        :return: Project information
+        Fetches project information from GitLab.
+
+        Sends an HTTP GET request using the instance's project_id to retrieve project details.
+        Returns a dictionary of project information on success, or logs an error and returns None
+        if the request fails.
         """
         # URL for the GitLab API endpoint
         url = f"{GITLAB_SERVER_URL}/api/v4/projects/{self.project_id}"
@@ -196,6 +199,23 @@ def find_files_by_keyword(self, keyword, branch_name="main"):
     # 构建带有身份验证信息的 URL
     def _build_authenticated_url(self, repo_url):
         # 如果 URL 使用 https
+        """
+        Build an authenticated GitLab repository URL using a private token.
+
+        This method embeds OAuth2 credentials into the provided repository URL by
+        injecting the GitLab private token. If the URL begins with "http://" or "https://",
+        the method constructs a new URL with the token included. Otherwise, it raises a
+        ValueError for unsupported URL schemes.
+
+        Args:
+            repo_url: The original repository URL (must begin with "http://" or "https://").
+
+        Returns:
+            An authenticated URL string with embedded OAuth2 credentials.
+
+        Raises:
+            ValueError: If the URL does not start with a supported scheme.
+        """
         token = GITLAB_PRIVATE_TOKEN
         if repo_url.startswith("https://"):
             return f"https://oauth2:{token}@{repo_url[8:]}"
@@ -207,7 +227,19 @@ def _build_authenticated_url(self, repo_url):
 
 def is_merge_request_opened(gitlab_payload) -> bool:
     """
-    判断是否是merge request打开事件
+    Determines if a merge request is open.
+
+    Checks whether the provided GitLab payload indicates an open merge request by verifying that its
+    "object_attributes" have either a state of "opened" with a merge status of "preparing" or a state
+    of "merged" with a merge status of "can_be_merged". If any error occurs during the evaluation, the
+    error is logged and False is returned.
+
+    Args:
+        gitlab_payload: Dictionary containing merge request attributes, including an "object_attributes"
+                        key with state and merge_status information.
+
+    Returns:
+        bool: True if the merge request meets one of the open criteria; otherwise, False.
     """
     try:
         gitlab_merge_request_old  = gitlab_payload.get("object_attributes").get("state") == "opened" and gitlab_payload.get("object_attributes").get("merge_status") == "preparing"

gitlab_integration/webhook_listener.py

@@ -11,6 +11,9 @@
 
 class WebhookListener:
     def __init__(self):
+        """
+        Initializes a WebhookListener instance.
+        """
         pass
 
     def handle_webhook(self):
@@ -51,7 +54,19 @@ def call_handle(self, gitlab_payload, event_type):
 
     def handle_merge_request(self, gitlab_payload, reply):
         """
-        处理合并请求事件
+        Process a merge request event triggered by a GitLab webhook.
+
+        If the merge request is open (as determined by is_merge_request_opened), logs the event,
+        extracts project and merge request identifiers from the payload, and starts an asynchronous
+        thread to process the merge using a ReviewEngine instance. Otherwise, returns a response
+        indicating that no review is necessary.
+
+        Args:
+            gitlab_payload: A dictionary containing the webhook payload with 'project' and 'object_attributes' keys.
+            reply: Data used to initialize the ReviewEngine for merge request processing.
+
+        Returns:
+            A tuple comprising a JSON response and an HTTP status code (200).
         """
         if is_merge_request_opened(gitlab_payload):
             log.info("首次merge_request ", gitlab_payload)

review_engine/handler/default_handler.py

@@ -65,6 +65,11 @@ def merge_handle(self, gitlabMergeRequestFetcher, gitlabRepoManager, hook_info,
         self.default_handle(changes, merge_info, hook_info, reply, model)
 
     def default_handle(self, changes, merge_info, hook_info, reply, model):
+        """
+        Processes merge request changes to generate and add code review replies.
+
+        Evaluates the list of changes and, if the file count is within the allowed threshold, creates a code review note using concurrent processing. When review information is generated, it adds detailed reply messages—including project and merge request details—to the reply object. If the review note is not produced (indicating that changes have already been merged) or if too many files are changed, the method adds a corresponding fallback or warning reply. If no valid changes are provided, it logs an error with contextual merge request information.
+        """
         if changes and len(changes) <= MAX_FILES:
             # Code Review 信息
             review_info = chat_review(changes, generate_review_note, model)