feat: library doc now generates a more RFW-like signature for arguments and argument defaults like ${SPACE}, ${EMPTY}, ${True}, etc. for the respective values

Author: d-biehl

packages/language_server/src/robotcode/language_server/robotframework/diagnostics/imports_manager.py

@@ -571,6 +571,7 @@ def clear_cache(self) -> None:
 
     @_logger.call
     async def get_command_line_variables(self) -> List[VariableDefinition]:
+        from robot.errors import DataError
         from robot.utils.text import split_args_from_name_or_path
 
         async with self._command_line_variables_lock:
@@ -634,6 +635,8 @@ async def get_command_line_variables(self) -> List[VariableDefinition]:
 
                     except (SystemExit, KeyboardInterrupt, asyncio.CancelledError):
                         raise
+                    except DataError:
+                        pass
                     except BaseException as e:
                         # TODO add diagnostics
                         self._logger.exception(e)

packages/language_server/src/robotcode/language_server/robotframework/diagnostics/library_doc.py

@@ -234,6 +234,29 @@ class KeywordArgumentKind(Enum):
     VAR_NAMED = "VAR_NAMED"
 
 
+def robot_arg_repr(arg: Any) -> Optional[str]:
+    from robot.running.arguments.argumentspec import ArgInfo
+
+    robot_arg = cast(ArgInfo, arg)
+
+    if robot_arg.default is ArgInfo.NOTSET:
+        return None
+
+    if robot_arg.default is None:
+        return "${None}"
+
+    if isinstance(robot_arg.default, (int, float, bool)):
+        return f"${{{robot_arg.default!r}}}"
+
+    if isinstance(robot_arg.default, str) and robot_arg.default == "":
+        return "${EMPTY}"
+
+    if isinstance(robot_arg.default, str) and robot_arg.default == "\\ \\":
+        return "${SPACE}"
+
+    return str(robot_arg.default_repr)
+
+
 @dataclass
 class KeywordArgumentDoc:
     name: str
@@ -251,15 +274,26 @@ def from_robot(arg: Any) -> KeywordArgumentDoc:
 
         return KeywordArgumentDoc(
             name=robot_arg.name,
-            default_value=robot_arg.default_repr,
+            default_value=robot_arg_repr(robot_arg),
             str_repr=str(arg),
             types=robot_arg.types_reprs,
             kind=KeywordArgumentKind[robot_arg.kind],
             required=robot_arg.required,
         )
 
     def __str__(self) -> str:
-        return self.str_repr
+        prefix = ""
+        if self.kind == KeywordArgumentKind.VAR_POSITIONAL:
+            prefix = "*"
+        elif self.kind == KeywordArgumentKind.VAR_NAMED:
+            prefix = "**"
+
+        return (
+            f"{prefix}{self.name!s}"
+            f"{(': ' + (' | '.join(f'{s}' for s in self.types))) if self.types else ''}"
+            f"{' =' if self.default_value is not None else ''}"
+            f"{f' {self.default_value!s}' if self.default_value else ''}"
+        )
 
     def __hash__(self) -> int:
         return id(self)
@@ -431,7 +465,7 @@ def to_markdown(self, add_signature: bool = True, header_level: int = 2, add_typ
             if result:
                 result += "\n\n"
 
-            result += f"##{'#'*header_level} Documentation:\n\n"
+            result += f"##{'#'*header_level} Documentation:\n"
 
             if self.doc_format == ROBOT_DOC_FORMAT:
                 result += MarkDownFormatter().format(self.doc)
@@ -452,10 +486,12 @@ def _get_signature(self, header_level: int, add_type: bool = True) -> str:
                 result = ""
 
         if self.args:
-            result += f"\n##{'#'*header_level} Arguments: \n\n"
+            result += f"\n##{'#'*header_level} Arguments: \n"
 
             result += "\n| | | | |"
-            result += "\n|:--- | --:|:--|:---|"
+            result += "\n|:--|:--|:--|:--|"
+
+            escaped_pipe = " \\| "
 
             for a in self.args:
                 prefix = ""
@@ -466,9 +502,10 @@ def _get_signature(self, header_level: int, add_type: bool = True) -> str:
 
                 result += (
                     f"\n| `{prefix}{a.name!s}`"
-                    f"| {'=' if a.default_value is not None else ''}"
-                    f"| {f'`{a.default_value!s}`' if a.default_value else ''}"
-                    f"| {' or '.join(f'`<{s}>`' for s in a.types) if a.types is not None else ''} |"
+                    f'{": " if a.types else " "}'
+                    f"| {escaped_pipe.join(f'`{s}`' for s in a.types) if a.types else ''} "
+                    f"| {'=' if a.default_value is not None else ''} "
+                    f"| {f'`{a.default_value!s}`' if a.default_value else ''} |"
                 )
 
         if self.tags:
@@ -705,7 +742,6 @@ def write_lines(*args: str) -> None:
             write_lines(
                 f"#{'#'*header_level} {(self.type.capitalize()) if self.type else 'Unknown'} *{self.name}*",
                 "",
-                "",
             )
 
             if self.version or self.scope:

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_references.test[references.robot-001-016-a_builtin_library].out

@@ -48,3 +48,12 @@ result:
       character: 16
       line: 1
   uri: tests/references.robot
+- !Location
+  range:
+    end:
+      character: 22
+      line: 1
+    start:
+      character: 11
+      line: 1
+  uri: tests/signature_help.robot

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_references.test[references.robot-001-021-a_builtin_library].out

@@ -48,3 +48,12 @@ result:
       character: 16
       line: 1
   uri: tests/references.robot
+- !Location
+  range:
+    end:
+      character: 22
+      line: 1
+    start:
+      character: 11
+      line: 1
+  uri: tests/signature_help.robot

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_references.test[references.robot-001-026-a_builtin_library].out

@@ -48,3 +48,12 @@ result:
       character: 16
       line: 1
   uri: tests/references.robot
+- !Location
+  range:
+    end:
+      character: 22
+      line: 1
+    start:
+      character: 11
+      line: 1
+  uri: tests/signature_help.robot

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_signature_help.test[signature_help.robot-003-026-library_signature].out

@@ -0,0 +1,28 @@
+data: !GeneratedTestData
+  character: 26
+  line: 3
+  name: library signature
+result: !SignatureHelp
+  active_parameter: null
+  active_signature: 0
+  signatures:
+  - activeParameter: 0
+    documentation:
+      kind: !MarkupKind 'MARKDOWN'
+      value: '#### Documentation:
+
+        This is the constructor of the class.
+
+
+        '
+    label: '(l: List[int] | None = ${None}, s: str = Hello World!, i: int = ${0},
+      b: bool = ${False})'
+    parameters:
+    - documentation: null
+      label: 'l: List[int] | None = ${None}'
+    - documentation: null
+      label: 's: str = Hello World!'
+    - documentation: null
+      label: 'i: int = ${0}'
+    - documentation: null
+      label: 'b: bool = ${False}'

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_signature_help.test[signature_help.robot-003-028-library_signature].out

@@ -0,0 +1,28 @@
+data: !GeneratedTestData
+  character: 28
+  line: 3
+  name: library signature
+result: !SignatureHelp
+  active_parameter: null
+  active_signature: 0
+  signatures:
+  - activeParameter: 0
+    documentation:
+      kind: !MarkupKind 'MARKDOWN'
+      value: '#### Documentation:
+
+        This is the constructor of the class.
+
+
+        '
+    label: '(l: List[int] | None = ${None}, s: str = Hello World!, i: int = ${0},
+      b: bool = ${False})'
+    parameters:
+    - documentation: null
+      label: 'l: List[int] | None = ${None}'
+    - documentation: null
+      label: 's: str = Hello World!'
+    - documentation: null
+      label: 'i: int = ${0}'
+    - documentation: null
+      label: 'b: bool = ${False}'

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_signature_help.test[signature_help.robot-003-030-library_signature].out

@@ -0,0 +1,28 @@
+data: !GeneratedTestData
+  character: 30
+  line: 3
+  name: library signature
+result: !SignatureHelp
+  active_parameter: null
+  active_signature: 0
+  signatures:
+  - activeParameter: 0
+    documentation:
+      kind: !MarkupKind 'MARKDOWN'
+      value: '#### Documentation:
+
+        This is the constructor of the class.
+
+
+        '
+    label: '(l: List[int] | None = ${None}, s: str = Hello World!, i: int = ${0},
+      b: bool = ${False})'
+    parameters:
+    - documentation: null
+      label: 'l: List[int] | None = ${None}'
+    - documentation: null
+      label: 's: str = Hello World!'
+    - documentation: null
+      label: 'i: int = ${0}'
+    - documentation: null
+      label: 'b: bool = ${False}'

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_signature_help.test[signature_help.robot-006-031-Suite_Setup_first_param].out

@@ -0,0 +1,25 @@
+data: !GeneratedTestData
+  character: 31
+  line: 6
+  name: Suite Setup first param
+result: !SignatureHelp
+  active_parameter: 0
+  active_signature: 0
+  signatures:
+  - activeParameter: 0
+    documentation:
+      kind: !MarkupKind 'MARKDOWN'
+      value: '#### Documentation:
+
+        This is a method of the class.
+
+
+        '
+    label: '(i: int, b: bool, l: List[int] | None = ${None})'
+    parameters:
+    - documentation: null
+      label: 'i: int'
+    - documentation: null
+      label: 'b: bool'
+    - documentation: null
+      label: 'l: List[int] | None = ${None}'

tests/robotcode/language_server/robotframework/parts/_regtest_outputs/rf41/test_signature_help.test[signature_help.robot-006-036-Suite_Setup_second_param].out

@@ -0,0 +1,25 @@
+data: !GeneratedTestData
+  character: 36
+  line: 6
+  name: Suite Setup second param
+result: !SignatureHelp
+  active_parameter: 1
+  active_signature: 0
+  signatures:
+  - activeParameter: 1
+    documentation:
+      kind: !MarkupKind 'MARKDOWN'
+      value: '#### Documentation:
+
+        This is a method of the class.
+
+
+        '
+    label: '(i: int, b: bool, l: List[int] | None = ${None})'
+    parameters:
+    - documentation: null
+      label: 'i: int'
+    - documentation: null
+      label: 'b: bool'
+    - documentation: null
+      label: 'l: List[int] | None = ${None}'