Improve facade method docstrings (such that first line is meaningful stand-alone)

src/serena/repl/api/ext_api.py

@@ -82,12 +82,16 @@ class ExternalProjectsApi(FacadeApi):
     @facade_method(corresponding_tool=QueryProjectTool)
     def project_context(self, project_name: str) -> ExternalProjectContextManager:
         """
-        Provides a context (for use in a `with` statement) within which all facades operate on the given external
-        project instead of the active one, with read-only access: e.g.
-        `with s.ext.project_context("other"): result = s.lsp.find_symbol("Foo")`.
+        Provides a context (for use in a `with` statement) within which all facades operate on the given external project
+        instead of the active one, with read-only access.
+
+        Example:
+        `with s.ext.project_context("other"): result = s.lsp.find_symbol("Foo")`
+
         Results obtained within the context can be used after it (they are self-contained).
 
         :param project_name: the name (or root path) of the project, as listed by `list_projects`
         :return: the context manager
+
         """
         return ExternalProjectContextManager(self._agent, project_name)

src/serena/repl/api/jb_api.py

@@ -211,6 +211,7 @@ class JetBrainsApi(FacadeApi):
     ) -> JetBrainsSymbolCollection:
         """
         Finds symbols and code entities (classes, methods, etc.) based on the given name path pattern.
+
         The returned symbol information can be used for edits or further queries.
         Specify `depth > 0` to retrieve children (e.g., methods of a class).
         Important: through `search_deps=True` dependencies can be searched, which
@@ -283,9 +284,9 @@ class JetBrainsApi(FacadeApi):
     @facade_method(corresponding_tool=JetBrainsFindReferencingSymbolsTool)
     def find_referencing_symbols(self, name_path: str, relative_path: str, max_answer_chars: int = -1) -> JetBrainsSymbolCollection:
         """
-        Finds all symbols that reference the given symbol — its callers / usages / dependents, i.e. the
-        symbols whose own definition (e.g. a method body) contains a reference to it. For each, returns its
-        name path, file, and the surrounding line of code.
+        Finds all symbols that reference the given symbol (its callers / usages / dependents)
+        i.e. the symbols whose own definition (e.g. a method body) contains a reference to it.
+        For each, returns its name path, file, and the surrounding line of code.
 
         :param name_path: name path of the symbol for which to find references
         :param relative_path: the relative path to the file containing the symbol (must be a file, not a directory)
@@ -317,8 +318,9 @@ class JetBrainsApi(FacadeApi):
         self, relative_path: str, depth: int = -1, max_answer_chars: int = -1, include_file_documentation: bool = False
     ) -> JetBrainsSymbolsOverview:
         """
-        Gets an overview of the top-level symbols defined in the given file (classes, methods, fields) — its
-        STRUCTURE, without their bodies. This is the cheap, structure-first way to learn what a file
+        Gets an overview of the top-level symbols defined in the given file (classes, methods, fields).
+
+        Returns STRUCTURE only, without bodies. This is the cheap, structure-first way to learn what a file
         contains: it costs far less context than reading the whole file.
 
         :param relative_path: the relative path to the file to get the overview of
@@ -443,6 +445,7 @@ class JetBrainsApi(FacadeApi):
     ) -> JsonObject:
         """
         Renames a symbol, file or directory throughout the codebase.
+
         Note: renaming in comments/text is on a best-effort basis by the IDE; if the symbol name is non-unique, further
         verification is recommended.
 
@@ -473,6 +476,7 @@ class JetBrainsApi(FacadeApi):
     ) -> JsonObject:
         """
         Moves a symbol, file or directory to a different location and automatically updates all references to affected symbols.
+
         **Important**: this should always be preferred to naive moving (e.g. via file system operations or edits)
         as it is much more reliable and efficient. It is always safe to use. For some symbols, moving may not be applicable,
         and will result in no edits and a suitable error message.
@@ -510,6 +514,7 @@ class JetBrainsApi(FacadeApi):
     ) -> JsonObject:
         """
         Safely deletes a symbol, file, or directory, checking for usages first and propagating deletion, if desired.
+
         Propagation means it is possible to request deleting of usages and cleaning up of unused code.
         Propagation is powerful for cleaning up code but should be used with care.
         **Important**: this should always be preferred to naive deleting (e.g. via file system operations or edits).
@@ -534,13 +539,13 @@ class JetBrainsApi(FacadeApi):
     @facade_method(beta=True, can_edit=True, corresponding_tool=JetBrainsInlineSymbol)
     def inline_symbol(self, name_path: str, relative_path: str, keep_definition: bool = False) -> JsonObject:
         """
-        Inlines a symbol (usually a method/function, but also classes may be amenable to inlining,
-        which turns invocation into anonymous class creation),
-        replacing all call sites with the symbol's body.
+        Inlines a symbol, replacing all call sites with the symbol's body.
+
         **Important**: this should always be preferred to naive inlining (e.g. via searching for references and
         editing them).
 
-        :param name_path: the name path of the symbol to inline.
+        :param name_path: the name path of the symbol to inline (usually a method/function, but also classes may be amenable to inlining,
+            which turns invocation into anonymous class creation)
         :param relative_path: the relative path to the file containing the symbol to inline.
         :param keep_definition: whether to keep the original method definition after inlining all call sites.
             May be ignored in some cases (e.g. when inlining a class).
@@ -564,6 +569,7 @@ class JetBrainsApi(FacadeApi):
     ) -> JsonObject:
         """
         Runs IDE inspections (code analysis) on the given file and returns the problems found.
+
         This leverages the full power of JetBrains' static analysis engine, including language-specific
         inspections, type checking, potential bugs, code style issues, and more.
 
@@ -591,8 +597,9 @@ class JetBrainsApi(FacadeApi):
         self, language: str | None = None, group_path_contains: str | None = None, max_answer_chars: int = -1
     ) -> JsonObject:
         """
-        Lists the available IDE inspections. Use this to discover which inspections can be passed
-        to `run_inspections` via `inspection_names`.
+        Lists available IDE inspections.
+
+        Use this to discover which inspections can be passed to `run_inspections` via `inspection_names`.
 
         :param language: optional language to filter by (e.g. "Java", "Python", "Kotlin").
         :param group_path_contains: optional substring to match against the inspection group path
@@ -605,7 +612,7 @@ class JetBrainsApi(FacadeApi):
 
     # debugging
 
-    @facade_method(beta=True)
+    @facade_method()
     def debug_eval_info(self) -> str:
         """
         Provides usage information for the debug REPL (method `debug_eval`)
@@ -614,7 +621,7 @@ class JetBrainsApi(FacadeApi):
         """
         return self._agent.prompt_factory.create_info_jet_brains_debug_repl()
 
-    @facade_method(beta=True, corresponding_tool=JetBrainsDebugTool)
+    @facade_method(corresponding_tool=JetBrainsDebugTool)
     def debug_eval(self, expression: str, repl_key: str = "default") -> str:
         """
         Provides debugging functionality (run configs, breakpoints, stepping, inspection, and evaluation)

src/serena/repl/api/lsp_api.py

@@ -381,8 +381,9 @@ class LspApi(FacadeApi):
     @facade_method(uses_project_server=True, optional=True, corresponding_tool=RestartLanguageServerTool)
     def restart_language_server(self) -> str:
         """
-        Restarts the language server(s). Use this only on explicit user request or after confirmation;
-        it may be necessary if a language server hangs.
+        Restarts the language server(s).
+
+        Use this only on explicit user request or after confirmation; it may be necessary if a language server hangs.
 
         :return: a success message
         """
@@ -394,8 +395,9 @@ class LspApi(FacadeApi):
     @facade_method(uses_project_server=True, corresponding_tool=GetSymbolsOverviewTool)
     def get_symbols_overview(self, relative_path: str, depth: int = -1, max_answer_chars: int = -1) -> LspSymbolCollection:
         """
-        Gets an overview of the top-level symbols defined in the given file (classes, methods, fields) — its
-        STRUCTURE, without their bodies. This is the cheap, structure-first way to learn what a file
+        Gets an overview of the symbols defined in the given file (classes, methods, fields, functions, etc.)
+
+        Returns STRUCTURE only, without bodies. This is the cheap, structure-first way to learn what a file
         contains: it costs far less context than reading the whole file.
 
         :param relative_path: the relative path to the file to get the overview of
@@ -450,6 +452,7 @@ class LspApi(FacadeApi):
     ) -> LspSymbolCollection:
         """
         Finds symbols and code entities (classes, methods, etc.) based on the given name path pattern.
+
         The returned symbol information can be used for edits or further queries.
         Specify `depth > 0` to also retrieve children/descendants (e.g., methods of a class).
 
@@ -534,8 +537,9 @@ class LspApi(FacadeApi):
         max_answer_chars: int = -1,
     ) -> LspReferenceCollection:
         """
-        Finds references to the symbol at the given `name_path`. The result will contain metadata about the referencing symbols
-        as well as a short code snippet around the reference.
+        Finds references to the symbol at the given `name_path`.
+
+        The result will contain metadata about the referencing symbols as well as a short code snippet around the reference.
 
         :param name_path: name path of the symbol
         :param relative_path: the relative path to the file containing the symbol for which to find references.
@@ -656,7 +660,9 @@ class LspApi(FacadeApi):
         self, relative_path: str, start_line: int = 0, end_line: int = -1, min_severity: int = 4, max_answer_chars: int = -1
     ) -> LspDiagnostics:
         """
-        Gets diagnostics for a file. Diagnostics are grouped as `relative_path -> severity -> name_path -> diagnostics_results`.
+        Gets diagnostics for a file.
+
+        Diagnostics are grouped as `relative_path -> severity -> name_path -> diagnostics_results`.
         If a diagnostic cannot be mapped to a symbol, it is grouped under the special name path `<file>`.
 
         :param relative_path: the relative path to the file to inspect.
@@ -694,9 +700,10 @@ class LspApi(FacadeApi):
         max_answer_chars: int = -1,
     ) -> LspDiagnostics:
         """
-        Gets diagnostics for the specified symbol. When `check_symbol_references` is true, diagnostics for all
-        referencing symbols are also included. The result is grouped as
-        `relative_path -> severity -> name_path -> diagnostics_results`.
+        Gets diagnostics for the specified symbol.
+
+        When `check_symbol_references` is true, diagnostics for all referencing symbols are also included.
+        The result is grouped as `relative_path -> severity -> name_path -> diagnostics_results`.
 
         :param name_path: the name path of the symbol to inspect.
         :param reference_file: optional file path used to disambiguate the symbol search.

src/serena/repl/api/mem_api.py

@@ -78,7 +78,7 @@ class MemoryApi(FacadeApi):
     @facade_method(corresponding_tool=ReadMemoryTool)
     def read_memory(self, memory_name: str) -> str:
         """
-        Reads a memory that is likely to be relevant to the current task, inferring relevance e.g. from the name.
+        Reads a memory.
 
         :param memory_name: the name of the memory
         :return: the memory's content
@@ -88,7 +88,8 @@ class MemoryApi(FacadeApi):
     @facade_method(can_edit=True, corresponding_tool=WriteMemoryTool)
     def write_memory(self, memory_name: str, content: str, max_chars: int = -1) -> str:
         """
-        Writes information about this project that can be useful for future tasks in md format.
+        Writes information (about the active project) to a memory.
+
         The name should be meaningful and can include "/" to organize into topics.
         If explicitly instructed, use the "global/" prefix for writing a memory that is shared across projects.
         References to other memories should be inside backticks and prefixed with mem:,