update docs

[mrT23]

PR Type

Enhancement, Documentation

---

Description

• Simplified code suggestion logic in pr_code_suggestions.py:
  • Removed conditional logic for is_extended
  • Unified num_code_suggestions assignment
  • Updated rank_suggestions method
• Enhanced 'improve' tool documentation:
  • Added detailed explanation of code suggestion generation strategy
  • Updated configuration options and tables
• Revised local configuration example in usage guide
• Removed num_code_suggestions from main configuration file

---

Changes walkthrough 📝

	Relevant files
Enhancement	pr_code_suggestions.py Simplify code suggestion logic                                                      pr_agent/tools/pr_code_suggestions.py Removed conditional logic for is_extended and simplified num_code_suggestions assignment Updated rank_suggestions method to remove reference to num_code_suggestions +2/-5
Documentation	improve.md Update 'improve' tool documentation                                            docs/docs/tools/improve.md Added new section explaining how many code suggestions are generated Removed outdated configuration options Updated configuration tables with current parameters +28/-18  automations_and_usage.md Revise local configuration example                                              docs/docs/usage-guide/automations_and_usage.md Updated example in local configuration file section +2/-2
Configuration changes	configuration.toml Update configuration file                                                                pr_agent/settings/configuration.toml Removed num_code_suggestions configuration option +0/-1

---

💡 PR-Agent usage: Comment /help "your question" on any pull request to receive relevant information

[qodo-merge-pro]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🏅 Score: 95

🧪 No relevant tests

🔒 No security concerns identified

🔀 Multiple PR themes Sub-PR theme: Simplify code suggestion logic Relevant files: pr_agent/tools/pr_code_suggestions.py Sub-PR theme: Update documentation for code suggestions Relevant files: docs/docs/tools/improve.md docs/docs/usage-guide/automations_and_usage.md Sub-PR theme: Remove unused configuration option Relevant files: pr_agent/settings/configuration.toml

⚡ Key issues to review Potential Redundancy The is_extended variable is still being set but not used after the simplification.

[qodo-merge-pro]

PR Code Suggestions ✨

Category	Suggestion	Score
Best practice	Use specific exception types in try-except blocks for more precise error handling Consider using a try-except block with a specific exception type instead of a bare except clause. This will make the error handling more precise and avoid catching unexpected exceptions. pr_agent/tools/pr_code_suggestions.py [43-46] try: self.is_extended = self._get_is_extended(args or []) -except: +except ValueError: # Replace with the specific exception type that _get_is_extended might raise self.is_extended = False Apply this suggestion Suggestion importance[1-10]: 7 Why: This suggestion enhances error handling precision and follows Python best practices, making the code more robust.	7
	Use an empty list as the default value for an optional parameter instead of None Consider using a default value of an empty list ([]) instead of None for the args parameter in the init method. This would eliminate the need for the or [] check in the self._get_is_extended() call. pr_agent/tools/pr_code_suggestions.py [41-44] -def __init__(self, pr_url: str, cli_mode=False, args: list = None, +def __init__(self, pr_url: str, cli_mode=False, args: list = [], ... - self.is_extended = self._get_is_extended(args or []) + self.is_extended = self._get_is_extended(args) Suggestion importance[1-10]: 6 Why: The suggestion improves code clarity and reduces the need for additional checks, but it's a minor optimization.	6
Organization best practice	✅ Use backticks for quoting variables or configuration names in documentation Suggestion Impact: The commit implemented the suggestion by enclosing configuration variables in backticks for better readability and consistency with code formatting. code diff: +- PR-Agent divides large PRs into 'chunks'. +- Each chunk contains up to `pr_code_suggestions.max_context_tokens` tokens (default: 14,000). + + +2) Generating suggestions: + +- For each chunk, PR-Agent generates up to `pr_code_suggestions.num_code_suggestions_per_chunk` suggestions (default: 4). Enclose configuration variables in backticks () for better readability and consistency with code formatting, as per the company's best practices. docs/docs/tools/improve.md [107-112] -- Each chunk contains up to pr_code_suggestions.max_context_tokens tokens (default: 14,000). +- Each chunk contains up to `pr_code_suggestions.max_context_tokens` tokens (default: 14,000). ... -- For each chunk, PR-Agent generates up to pr_code_suggestions.num_code_suggestions_per_chunk suggestions (default: 4). +- For each chunk, PR-Agent generates up to `pr_code_suggestions.num_code_suggestions_per_chunk` suggestions (default: 4). Suggestion importance[1-10]: 5 Why: This suggestion improves documentation readability and consistency, but it's a minor formatting change.	5

💡 Need additional feedback ? start a PR chat

[mrT23]

/help

[qodo-merge-pro]

PR Agent Walkthrough 🤖

Welcome to the PR Agent, an AI-powered tool for automated pull request analysis, feedback, suggestions and more.

Here is a list of tools you can use to interact with the PR Agent:

Tool	Description	Trigger Interactively 💎
DESCRIBE	Generates PR description - title, type, summary, code walkthrough and labels	Run
REVIEW	Adjustable feedback about the PR, possible issues, security concerns, review effort and more	Run
IMPROVE	Code suggestions for improving the PR	Run
UPDATE CHANGELOG	Automatically updates the changelog	Run
ADD DOCS 💎	Generates documentation to methods/functions/classes that changed in the PR	Run
TEST 💎	Generates unit tests for a specific component, based on the PR code change	Run
IMPROVE COMPONENT 💎	Code suggestions for a specific component that changed in the PR	Run
ANALYZE 💎	Identifies code components that changed in the PR, and enables to interactively generate tests, docs, and code suggestions for each component	Run
ASK	Answering free-text questions about the PR	[*]
GENERATE CUSTOM LABELS 💎	Generates custom labels for the PR, based on specific guidelines defined by the user	[*]
CI FEEDBACK 💎	Generates feedback and analysis for a failed CI job	[*]
CUSTOM PROMPT 💎	Generates custom suggestions for improving the PR code, derived only from a specific guidelines prompt defined by the user	[*]
SIMILAR ISSUE	Automatically retrieves and presents similar issues	[*]

(1) Note that each tool be triggered automatically when a new PR is opened, or called manually by commenting on a PR.

(2) Tools marked with [*] require additional parameters to be passed. For example, to invoke the /ask tool, you need to comment on a PR: /ask "<question content>". See the relevant documentation for each tool for more details.

[mrT23]

/help "when should i use 'extra instructions' ? when should I use 'best practices' ? when should I use 'custom prompt' ? "

[qodo-merge-pro]

Question:

when should i use 'extra instructions' ? when should I use 'best practices' ? when should I use 'custom prompt' ?

Answer:

1. Extra Instructions:

   • Use when you want to give additional, specific guidance to the AI model for a particular tool, especially the 'improve' tool.
   • Ideal for temporary or task-specific instructions, like "Answer in Japanese" or "Don't suggest adding try-except blocks".
   • Can be set in the configuration file or used as a parameter in command-line usage.

2. Best Practices:

   • Use when you want to establish general coding standards and guidelines for your entire repository or organization.
   • Create a 'best_practices.md' wiki page with clear, concise guidelines (recommended 800 lines or fewer).
   • The AI will reference these practices when suggesting improvements, labeling them as "Organization best practice".

3. Custom Prompt:

   • Use when you want to create a highly specific set of instructions for code suggestions.
   • Defined in the configuration file under [pr_custom_prompt].
   • Allows you to be the prompter, focusing the AI on particular aspects of code review.
   • Useful for tailoring the AI's suggestions to your project's specific needs.

In summary, use extra instructions for tool-specific guidance, best practices for organization-wide standards, and custom prompts for highly tailored code suggestion focus.

Relevant Sources:

• https://pr-agent-docs.codium.ai/tools/improve#usage-tips
• https://pr-agent-docs.codium.ai/tools/custom_prompt#example-usage
• https://pr-agent-docs.codium.ai/usage-guide/additional_configurations#extra-instructions