docs(openspec): update the rf75-argument-docs change after its implementation

All tasks are done. Documented arguments are listed once like Libdoc does
instead of a table plus a separate list, and names documented without
being arguments are kept.

Author: d-biehl

openspec/changes/rf75-argument-docs/design.md

@@ -26,19 +26,19 @@ See proposal.md. Verified facts that shape the design:
 
 ### D1: Mirror RF on RobotCode's own dataclasses
 
-`ArgumentInfo` gains `doc: str = ""` and `type_docs: Optional[Dict[str, str]] = None` (used type name → TypeDoc name); `KeywordDoc` gains `return_doc: str = ""`, `raises: Optional[List[Tuple[str, str]]] = None` (docstring order) and `return_type_docs: Optional[Dict[str, str]] = None`; `KeywordDoc.__setstate__` falls back to field defaults instead of `None`. The `support-rf75` docstring helper returns `DocInfo.args/returns/raises` in addition to doc and tags and the three keyword sites store them; the `type_docs` map is copied from the RF walk that `_get_type_docs` already performs, extended to the return type as RF's `TypeDocBuilder` does. Alternatives: extending RobotCode's `ArgumentSpec` (the resolver model, `None` for error handlers, pickle-unsafe `__setstate__`) or parsing at render time in every consumer (five call sites, repeated parsing, no data for completion). New fields default-safe with the cache: the release bump rebuilds it, and `__setstate__` covers developer caches.
+`ArgumentInfo` gains `doc: str = ""` and `type_docs: Optional[Dict[str, str]] = None` (used type name → TypeDoc name); `KeywordDoc` gains `return_doc: str = ""`, `raises: Optional[List[Tuple[str, str]]] = None` (docstring order), `return_type_docs: Optional[Dict[str, str]] = None` and `extra_argument_docs: Optional[List[Tuple[str, str]]] = None` (added during implementation: descriptions of names that are no arguments of the keyword, see D2); `KeywordDoc.__setstate__` falls back to field defaults instead of `None`. The `support-rf75` docstring helper returns `DocInfo.args/returns/raises` in addition to doc and tags and the three keyword sites store them; the `type_docs` map is copied from the RF walk that `_get_type_docs` already performs, extended to the return type as RF's `TypeDocBuilder` does. Alternatives: extending RobotCode's `ArgumentSpec` (the resolver model, `None` for error handlers, pickle-unsafe `__setstate__`) or parsing at render time in every consumer (five call sites, repeated parsing, no data for completion). New fields default-safe with the cache: the release bump rebuilds it, and `__setstate__` covers developer caches.
 
 ### D2: Sections are separated only on RF ≥ 7.5
 
-Behaviour equals the installed Libdoc: on 7.5 the text loses the sections (this replaces `support-rf75`'s "keep the text" rule and its branch that kept the original text when sections exist — that branch is deleted, and the `support-rf75` test assertion that the `Args:` text is present in `doc` is inverted for RF ≥ 7.5), on ≤ 7.4 the sections stay in the text. The Markdown normalisation of D4/D5, by contrast, is not version-gated: it applies to every documentation declared as Markdown. Unknown argument names in `Args:` are kept in the description list (Libdoc fails the keyword; RobotCode must not).
+Behaviour equals the installed Libdoc: on 7.5 the text loses the sections (this replaces `support-rf75`'s "keep the text" rule and its branch that kept the original text when sections exist — that branch is deleted, and the `support-rf75` test assertion that the `Args:` text is present in `doc` is inverted for RF ≥ 7.5), on ≤ 7.4 the sections stay in the text. The Markdown normalisation of D4/D5, by contrast, is not version-gated: it applies to every documentation declared as Markdown. Unknown argument names in `Args:` are kept in the description list (Libdoc fails the keyword; RobotCode must not) — typically names accepted through `**kwargs`; they are stored in `KeywordDoc.extra_argument_docs` because `ArgumentInfo.doc` only exists for real arguments.
 
-### D3: Description list below the unchanged table
+### D3: Documented arguments are listed once, like Libdoc does
 
-`_get_signature` keeps the 4-column table and appends, only when any argument has a description, a list `- \`name\`: description` (continuation lines indented, block Markdown preserved, a description starting with a list marker is guarded by a blank line), then `**Return Type**: \`T\` — return description` (or `**Returns**: …` without a type) and `**Raises**:` with `- \`Exception\`: description` items, all inside the signature part so `to_markdown(False)` stays the documentation body. Rejected: a fifth table column (single-line cells cannot hold multi-line descriptions, lists or code; verified to wrap into 12-character cells in the REPL at 80 columns) and Libdoc's bullet layout (changes every keyword's look and the documented REPL output).
+Maintainer decision after seeing the first implementation (the unchanged table followed by a separate description list read as if the arguments were named twice): follow Robot Framework. Its Libdoc takes the sections completely out of the documentation and writes everything it found as separate parts, and its Markdown output (`libdocpkg/markdownformatter.py`) lists every argument once as `* \`name\` (type: …, default: …) -` followed by the description. `_get_signature` therefore renders, when any argument has a description, a list ``- `name`: `type` = `default` — description`` (continuation lines indented, block Markdown preserved, a description starting with a list marker gets its own block, names documented without being arguments appended) instead of the table; a keyword without descriptions keeps the 4-column table byte for byte. Then `**Return Type**: \`T\` — return description` (or `**Returns**: …` without a type) and `**Raises**:` with `- \`Exception\`: description` items, all inside the signature part so `to_markdown(False)` stays the documentation body. Rejected: the table plus a separate list (the first implementation), and a fifth table column (single-line cells cannot hold multi-line descriptions, lists or code; verified to wrap into 12-character cells in the REPL at 80 columns).
 
 ### D4: Reference links resolved through a hook
 
-A new pure module `packages/robot/src/robotcode/robot/utils/markdown_docs.py` resolves `[Name]`, `[Name][]` and `[text][Name]` outside code spans, fenced blocks, images and escaped brackets against a target set derived from the `LibraryDoc`: keyword names, TypeDoc names plus the used type names/aliases from `type_docs`, introduction headings, introduction reference definitions and the five Libdoc default names, matched caselessly and spacelessly. A `link_resolver(kind, name) -> Optional[str]` callback chooses the target: by default keywords, types and sections become inline code (the look Robot-format `` `name` `` references already have in hovers), introduction-defined references become inline links; full-page contexts (REPL `.doc`, HTTP Markdown view) pass a resolver producing `#slug` anchors, the REPL `.kw` view one producing `kw:` links. Unknown names stay literal, as Python-Markdown leaves them. `command:` links for VS Code are not generated (tree view and REPL cannot execute them) but fit the same hook later.
+A new pure module `packages/robot/src/robotcode/robot/utils/markdown_docs.py` resolves `[Name]`, `[Name][]` and `[text][Name]` outside code spans, fenced blocks, images and escaped brackets against a target set derived from the `LibraryDoc`: keyword names, TypeDoc names plus the used type names/aliases from `type_docs`, introduction headings, introduction reference definitions and the five Libdoc default names, matched caselessly and spacelessly. A `link_resolver(kind, name) -> Optional[str]` callback chooses the target: by default keywords, types and sections become inline code (the look Robot-format `` `name` `` references already have in hovers), introduction-defined references become inline links; full-page contexts (REPL `.doc`, HTTP Markdown view) pass a resolver producing `#slug` anchors, the REPL `.kw` view one producing `kw:` links. Unknown names stay literal, as Python-Markdown leaves them. A reference definition is never passed to the resolver: it always links to its URL (found during implementation: the anchor resolver of the full-page views would otherwise turn `[VAR syntax]` into a dead `#varsyntax` anchor). `command:` links for VS Code are not generated (tree view and REPL cannot execute them) but fit the same hook later.
 
 ### D5: Markdown headings, TOC and admonitions mirror the Robot-format rendering
 

openspec/changes/rf75-argument-docs/proposal.md

@@ -7,7 +7,7 @@ Robot Framework 7.5 documents its standard libraries with Google-style docstring
 ## What Changes
 
 - **Structured argument documentation.** On RF ≥ 7.5 the Google-style sections are separated from the documentation text (as RF's Libdoc does) and stored on RobotCode's documentation model: per-argument descriptions, return description and raised exceptions. On older versions the text stays as it is (Libdoc parity).
-- **Rendering.** Keyword hover, the keywords tree view tooltips, the REPL `.kw`/`.doc` output and the Markdown documentation view keep the existing argument table and add, only when descriptions exist, a description list below it plus `Returns`/`Raises` blocks. Signature help shows the argument description together with the argument's type documentation; named-argument completion items get the description as documentation.
+- **Rendering.** Keyword hover, the keywords tree view tooltips, the REPL `.kw`/`.doc` output and the Markdown documentation view list, when descriptions exist, every argument once with type, default value and description as Libdoc does (keywords without descriptions keep the argument table), plus `Returns`/`Raises` blocks. Signature help shows the argument description together with the argument's type documentation; named-argument completion items get the description as documentation.
 - **Markdown documentation normalisation.** For libraries documented in Markdown: `[Name]` reference links to keywords, types, introduction sections and Libdoc's default targets are resolved (inline code in hover/signature/completion, in-document anchors in full-page views such as the REPL `.doc` viewer and the Markdown web view, and keyword links in the REPL); reference definitions from the library introduction are inlined; `%TOC%` becomes a two-level table of contents; ATX headings are shifted one level like Robot-format headings are today; GitHub-style admonitions (`> [!WARNING]`) get a readable fallback since neither VS Code hovers, LSP4IJ nor the REPL render them.
 - **Type resolution.** Arguments carry the map from used type names to type documentation that RF computes, so signature help and value completion find the documentation of aliased enums/TypedDicts and of standard types whose documentation name differs from the type name (`int` → `integer`, a pre-existing gap on RF ≥ 6.1). Return types are included.
 - No change for libraries whose documentation is not in Markdown format and has no Google-style sections: their hover output stays byte-identical. Markdown-format libraries are normalised on every Robot Framework version (the format is accepted by older versions too); structured sections exist only on RF ≥ 7.5.
@@ -27,7 +27,7 @@ Depends on `support-rf75` (non-mutating docstring helper, `parse_docstring` impo
 
 ## Impact
 
-- `packages/robot/src/robotcode/robot/diagnostics/library_doc.py`: `ArgumentInfo` (`doc`, `type_docs`), `KeywordDoc` (`return_doc`, `raises`, `return_type_docs`, `__setstate__` defaults), the `support-rf75` docstring helper (returns sections; its keep-the-text branch is removed), `_get_signature`/`to_markdown` rendering, `LibraryDoc.get_types_for_argument`, `LibraryDoc.to_markdown` Markdown branch, `VariablesDoc.to_markdown` (forwards the resolver), `TypeDoc.to_markdown`, `_create_toc`.
+- `packages/robot/src/robotcode/robot/diagnostics/library_doc.py`: `ArgumentInfo` (`doc`, `type_docs`), `KeywordDoc` (`return_doc`, `raises`, `return_type_docs`, `extra_argument_docs`, `argument_to_markdown`, `__setstate__` defaults), the `support-rf75` docstring helper (returns sections; its keep-the-text branch is removed), `_get_signature`/`to_markdown` rendering, `LibraryDoc.get_types_for_argument`, `LibraryDoc.to_markdown` Markdown branch, `VariablesDoc.to_markdown` (forwards the resolver), `TypeDoc.to_markdown`, `_create_toc`.
 - New `packages/robot/src/robotcode/robot/utils/markdown_docs.py`: pure Markdown normalisation functions (heading shift, TOC, reference links, admonitions) next to the existing `markdownformatter.py`.
 - `packages/language_server/.../parts/signature_help.py` (both code paths), `completion.py` (value completion type lookup, named-argument documentation), `http_server.py` (anchor resolver for the Markdown view); hover and tree view unchanged.
 - `packages/repl/src/robotcode/repl/console_interpreter.py` (`.kw`/`.doc`, runtime fallback), `prompt_toolkit_interpreter.py` (keyword link resolver), `_pt/doc_viewer.py` (anchor map for shifted headings/TOC).

openspec/changes/rf75-argument-docs/specs/keyword-documentation-rendering/spec.md

@@ -8,11 +8,11 @@ Defines how RobotCode renders keyword and library documentation across its surfa
 
 ### Requirement: Argument descriptions are rendered with the signature
 
-When a keyword has documented arguments, the rendered keyword documentation SHALL show, after the argument table, one entry per documented argument with its name and description; multi-line descriptions SHALL be preserved. When a return description exists it SHALL be shown with the return type (`**Return Type**: \`T\` — description`, or `**Returns**: description` without a type); raised exceptions SHALL be listed with their descriptions. Keywords whose documentation is not in Markdown format and has no argument, return or raises description SHALL render exactly as before.
+When a keyword has documented arguments, the rendered keyword documentation SHALL list every argument once, with its type, its default value and its description, as Robot Framework's Libdoc lists them, instead of showing the argument table and the descriptions separately; multi-line descriptions SHALL be preserved. A keyword without argument descriptions SHALL keep the argument table. When a return description exists it SHALL be shown with the return type (`**Return Type**: \`T\` — description`, or `**Returns**: description` without a type); raised exceptions SHALL be listed with their descriptions. Keywords whose documentation is not in Markdown format and has no argument, return or raises description SHALL render exactly as before.
 
 #### Scenario: Standard-library keyword on RF 7.5
 - **WHEN** the hover for `Log` (BuiltIn) is shown on RF 7.5
-- **THEN** the argument table is followed by entries such as `message`: "The message to log." and `level`: "The log level to use."
+- **THEN** the arguments are listed as entries such as `message`: `object` — "The message to log." and `level`: … = `INFO` — "The log level to use.", and no argument is named twice
 - **AND** the documentation text below contains no `Args:` block
 
 #### Scenario: Keyword with return and raises documentation

openspec/changes/rf75-argument-docs/specs/library-documentation-extraction/spec.md

@@ -6,7 +6,7 @@
 
 ### Requirement: Tags declared in documentation are extracted
 
-RobotCode SHALL treat tags declared in keyword documentation — the `Tags:` section of a Python keyword docstring and of a resource keyword's `[Documentation]` — as keyword tags, merged with tags declared via `[Tags]` or `robot_tags`. A keyword whose merged tags contain `robot:private` SHALL be private. In resource keywords a documentation tag written as `-name` SHALL remove `name` from the merged tags; in library keywords it SHALL be kept literally. The `Tags:` section SHALL NOT appear in the rendered documentation text. Tags and privacy SHALL be identical on every supported Robot Framework version.
+RobotCode SHALL treat tags declared in keyword documentation — the `Tags:` section of a Python keyword docstring and of a resource keyword's `[Documentation]` — as keyword tags, merged with tags declared via `[Tags]` or `robot_tags`. A keyword whose merged tags contain `robot:private` SHALL be private. In resource keywords a documentation tag written as `-name` SHALL remove `name` from the merged tags on Robot Framework ≥ 7.4 (the first version whose Libdoc does so; older versions keep it literally); in library keywords it SHALL be kept literally. The `Tags:` section SHALL NOT appear in the rendered documentation text, in any form the installed Robot Framework recognises (every `Tags:` section on RF ≥ 7.5, a trailing `Tags:` line on older versions). Tags and privacy SHALL be the ones Robot Framework's own Libdoc reports for the installed version, identical on RF 7.4 and RF 7.5.
 
 #### Scenario: Library keyword docstring with a Tags section
 - **WHEN** a Python keyword's docstring ends with `Tags: alpha, beta` and the library is documented on RF 7.4 and on RF 7.5
@@ -18,8 +18,8 @@ RobotCode SHALL treat tags declared in keyword documentation — the `Tags:` sec
 - **THEN** the keyword is private (hover marks it as private, and it is deprioritised when a non-private keyword with the same name exists)
 
 #### Scenario: Negated documentation tag in a resource keyword
-- **WHEN** a resource keyword has `[Tags]    keep    stay` and a `[Documentation]` ending with `Tags: -keep, other`
-- **THEN** the keyword's tags are `other` and `stay`
+- **WHEN** a resource keyword has `[Tags]    keep    stay` and a `[Documentation]` ending with `Tags: -keep, other` and is documented on RF 7.4 and on RF 7.5
+- **THEN** the keyword's tags are `other` and `stay` on both versions
 
 ## REMOVED Requirements
 
@@ -31,7 +31,7 @@ RobotCode SHALL treat tags declared in keyword documentation — the `Tags:` sec
 
 ### Requirement: Google-style sections become structured documentation
 
-On Robot Framework ≥ 7.5 RobotCode SHALL separate the `Args:`, `Returns:` and `Raises:` sections (with the section names Robot Framework accepts) from a keyword's documentation into per-argument descriptions, a return description and a list of raised exceptions with descriptions, for library keywords and for resource keywords, without modifying Robot Framework's objects. The remaining documentation text SHALL no longer contain those sections. On older versions the documentation text SHALL stay unchanged and the structured fields SHALL be empty. A description for an argument the keyword does not have SHALL NOT cause an error.
+On Robot Framework ≥ 7.5 RobotCode SHALL separate the `Args:`, `Returns:` and `Raises:` sections (with the section names Robot Framework accepts) from a keyword's documentation into per-argument descriptions, a return description and a list of raised exceptions with descriptions, for library keywords and for resource keywords, without modifying Robot Framework's objects. The remaining documentation text SHALL no longer contain those sections. On older versions the documentation text SHALL stay unchanged and the structured fields SHALL be empty. A description for an argument the keyword does not have (for example a name accepted through `**kwargs`) SHALL NOT cause an error and SHALL be kept with the argument descriptions.
 
 #### Scenario: Library keyword with Google-style sections
 - **WHEN** a Python keyword `paint(shade, *items)` documents `Args:` for `shade` and `*items`, `Returns:` and `Raises: ValueError` and the library is documented on RF 7.5