Add to user tools guide

docs/ADD_DOCUMENTATION.md

@@ -0,0 +1,14 @@
+# Add Documentation Tool
+The `add_docs` tool scans the PR code changes, and automatically suggests documentation for the undocumented code components (functions, classes, etc.).
+
+It can be invoked manually by commenting on any PR:
+```
+/add_docs
+```
+For example:
+<kbd><img src=./../pics/add_docs_comment.png width="768"></kbd>
+<kbd><img src=./../pics/add_docs.png width="768"></kbd>
+
+### Configuration options
+ - `docs_style`: The exact style of the documentation (for python docstring). you can choose between: `google`, `numpy`, `sphinx`, `restructuredtext`, `plain`. Default is `sphinx`.
+ - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".

docs/TOOLS_GUIDE.md

@@ -5,5 +5,6 @@
 - [ASK](./ASK.md)
 - [SIMILAR_ISSUE](./SIMILAR_ISSUE.md)
 - [UPDATE CHANGELOG](./UPDATE_CHANGELOG.md)
+- [ADD DOCUMENTATION](./ADD_DOCUMENTATION.md)
 
 See the **[installation guide](/INSTALL.md)** for instructions on how to setup PR-Agent.

pr_agent/settings/configuration.toml

@@ -49,8 +49,7 @@ final_clip_factor = 0.9
 
 [pr_add_docs] # /add_docs #
 extra_instructions = ""
-docs_style = "Google Style" # "Google Style", "Numpy Style", "Sphinx Style", "PEP257", "reStructuredText"
-max_number_of_calls = 5
+docs_style = "Sphinx Style" # "Google Style with Args, Returns, Attributes...etc", "Numpy Style", "Sphinx Style", "PEP257", "reStructuredText"
 
 [pr_update_changelog] # /update_changelog #
 push_changelog_changes=false

pr_agent/settings/pr_add_docs.toml

@@ -32,7 +32,7 @@ __old hunk__
 
 Specific instructions:
 - Try to identify edited/added code components (classes/functions/methods...) that are undocumented. and generate {{ docs_for_language }} for each one.
-- If there are edited/added code components, but they are already documented, ignore them.
+- If there are documented (any type of {{ language }} documentation) code components in the PR, Don't generate {{ docs_for_language }} for them.
 - Ignore code components that don't appear fully in the '__new hunk__' section. For example. you must see the component header and body,
 - Make sure the {{ docs_for_language }} starts and ends with standart {{ language }} {{ docs_for_language }} signs.
 - The {{ docs_for_language }} should be in standard format.

pr_agent/tools/pr_add_docs.py

@@ -21,12 +21,6 @@ class PRAddDocs:
             self.git_provider.get_languages(), self.git_provider.get_files()
         )
 
-        # extended mode
-        try:
-            self.is_extended = any(["extended" in arg for arg in args])
-        except:
-            self.is_extended = False
-
         self.ai_handler = AiHandler()
         self.patches_diff = None
         self.prediction = None
@@ -51,20 +45,17 @@ class PRAddDocs:
         try:
             logging.info('Generating code Docs for PR...')
             if get_settings().config.publish_output:
-                self.git_provider.publish_comment("Preparing review...", is_temporary=True)
+                self.git_provider.publish_comment("Generating Documentation...", is_temporary=True)
 
-            logging.info('Preparing PR review...')
-            if not self.is_extended:
-                await retry_with_fallback_models(self._prepare_prediction)
-                data = self._prepare_pr_code_docs()
-            else:
-                data = await retry_with_fallback_models(self._prepare_prediction_extended)
+            logging.info('Preparing PR documentation...')
+            await retry_with_fallback_models(self._prepare_prediction)
+            data = self._prepare_pr_code_docs()
             if (not data) or (not 'Code Documentation' in data):
                 logging.info('No code documentation found for PR.')
                 return
 
             if get_settings().config.publish_output:
-                logging.info('Pushing PR review...')
+                logging.info('Pushing PR documentation...')
                 self.git_provider.remove_initial_comment()
                 logging.info('Pushing inline code documentation...')
                 self.push_inline_docs(data)
@@ -97,8 +88,8 @@ class PRAddDocs:
         return response
 
     def _prepare_pr_code_docs(self) -> Dict:
-        review = self.prediction.strip()
-        data = load_yaml(review)
+        docs = self.prediction.strip()
+        data = load_yaml(docs)
         if isinstance(data, list):
             data = {'Code Documentation': data}
         return data
@@ -167,37 +158,7 @@ class PRAddDocs:
 
         return new_code_snippet
 
-    async def _prepare_prediction_extended(self, model: str) -> dict:
-        logging.info('Getting PR diff...')
-        patches_diff_list = get_pr_multi_diffs(self.git_provider, self.token_handler, model,
-                                               max_calls=get_settings().pr_add_docs.max_number_of_calls)
 
-        logging.info('Getting multi AI predictions...')
-        prediction_list = []
-        for i, patches_diff in enumerate(patches_diff_list):
-            logging.info(f"Processing chunk {i + 1} of {len(patches_diff_list)}")
-            self.patches_diff = patches_diff
-            prediction = await self._get_prediction(model)
-            prediction_list.append(prediction)
-        self.prediction_list = prediction_list
-
-        data = {}
-        for prediction in prediction_list:
-            self.prediction = prediction
-            data_per_chunk = self._prepare_pr_code_docs()
-            if "Code Documentation" in data:
-                data["Code Documentation"].extend(data_per_chunk["Code Documentation"])
-            else:
-                data.update(data_per_chunk)
-        self.data = data
-        return data
-
-
-"""
-This function determines the type of documentation to generate based on the main language of the PR.
-It supports Javadocs for Java, Docstrings for Python, Lisp, and Clojure, JSdocs for JavaScript and TypeScript,
-and Doxygen for C++. For other languages, it defaults to generating generic Docs.
-"""
 def get_docs_for_language(language, style):
     language = language.lower()
     if language == 'java':