rust-lang / rust-lang/rust-analyzer

Auto-renumber ordered lists in doc comments

Open
#22,578 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-feature
Dominant language
Rust
Stars
16.9k
Forks
2.2k
Avg merge
1d 12h
Merged PRs (30d)
72

Description

rust-analyzer could improve editing support for ordered Markdown lists in Rust doc comments by automatically maintaining numbering in ordered lists.

Example:

/// 1. Parse the input.
/// 2. Validate the result.
/// 3. Emit diagnostics.

If a new item is inserted between 1 and 2:

/// 1. Parse the input.
/// 2. Normalize paths.
/// 2. Validate the result.
/// 3. Emit diagnostics.

rust-analyzer could automatically update the numbering to:

/// 1. Parse the input.
/// 2. Normalize paths.
/// 3. Validate the result.
/// 4. Emit diagnostics.

The same logic could also correct existing numbering mistakes:

/// 1. First step.
/// 2. Second step.
/// 4. Third step.

/// 1. First step.
/// 2. Second step.
/// 3. Third step.

Suggested behavior:

Detect ordered Markdown lists in ///, //!, /** /, and /! */ doc comments.
Automatically renumber subsequent items when a list item is inserted, removed, moved, or pasted.
Detect and offer a quick fix for inconsistent numbering in existing lists.
Support nested ordered lists and mixed indentation where possible.
Work with both explicit numbering and Markdown's common 1. style.
Limit the feature to doc comments so ordinary comments are unaffected.

This would make maintaining long documentation lists significantly more convenient and help prevent numbering mistakes from accumulating over time.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing rust-analyzer's handling of Rust doc comments and Markdown ordered lists, including the ///, //!, /** /, and /! */ forms named in the issue. Define the supported behavior for insertion, removal, movement, pasting, nested lists, and numbering fixes, then verify that ordinary comments remain unaffected.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.