Skip to content

Commit 5e29b8a

Browse files
gauravagerwalagauravagerwala
committed
Update design for PR rust-lang#16144: Parse doc comment markdown only once
1 parent 4d6fa3c commit 5e29b8a

File tree

2 files changed

+92
-0
lines changed

2 files changed

+92
-0
lines changed

‎.exp/design-workflow-5-lint-development.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,38 @@ sequenceDiagram
6262
Driver->>Compiler: run compilation with registered lints
6363
Store->>Compiler: execute lint passes during compilation phases
6464
Compiler->>User: output diagnostics from lints
65+
66+
## Doc Lint Event Processing Sequence Diagram
67+
### (New sub-flow for documentation lints, added by PR #16144)
68+
69+
```mermaid
70+
sequenceDiagram
71+
participant Pass as "Documentation Pass"
72+
participant CA as check_attrs
73+
participant CD as check_doc
74+
participant P as Parser
75+
participant SM as State Machines
76+
participant CX as LateContext
77+
78+
Pass->>+CA: check doc attributes
79+
CA->>+CD: doc, fragments, valid_idents
80+
CD->>+P: pulldown_cmark::Parser::new(doc, opts, callback)
81+
loop for each event
82+
P->>+CD: (Event, Range<usize>)
83+
CD->>+SM: sm.check(cx, event, range, doc, fragments)
84+
Note right of SM: Accumulate state<br/>e.g., track pending links or paragraph ends
85+
alt lint trigger
86+
SM->>+CX: span_lint_and_then(lint, span, msg, sugg)
87+
end
88+
SM-->>-CD:
89+
end
90+
CD-->>-CA: DocHeaders
91+
CA-->>-Pass:
92+
P-->>-CD:
93+
94+
Note over CD, SM: Single parse, modular event processing
95+
```
96+
6597
\`\`\`
6698

6799
## Additional High-Level Design Aspects
@@ -90,6 +122,7 @@ This ensures new lints are automatically included when compiling \`clippy_lints\
90122
- **Hooks**: Lints impl methods like \`check_expr\`, \`check_item\` using visitor patterns or queries via \`cx\`.
91123
- **Groups and Levels**: Lints assigned to categories (correctness, style, etc.) auto-grouped by \`LintListBuilder\`; levels (Allow, Warn, Deny).
92124
- **Fixes**: Use \`rustfix::diagnostics::Diagnostic::fix` for auto-fixes via \`--fix\`.
125+
- **Documentation Lints**: Documentation lints in \`clippy_lints/src/doc/\` are grouped under the \`Documentation\` late lint pass. Markdown parsing of doc comments is performed once per attribute group in the \`check_doc\` function, generating \`pulldown_cmark::Event\`s with byte ranges. Specific lints like \`doc_link_code\` and \`doc_paragraphs_missing_punctuation\` implement state machines as structs (e.g., \`LinkCode\`, \`MissingPunctuation\`) with a \`check\` method that processes each event, maintaining internal state (e.g., pending links, paragraph position) and emitting diagnostics via \`span_lint_and_then\` when patterns match. These are instantiated in \`check_doc\` and called in its main event loop. This design, refined in [PR #16144](https://github.com/rust-lang/rust-clippy/pull/16144), ensures efficient single-pass analysis and modularity. New doc lints should adopt this event-driven pattern.
93126

94127
### Edge Cases and Extensibility
95128

‎pr-analysis-16144.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# PR #16144: Workflow Design Impact Analysis
2+
3+
## Affected Workflows
4+
- Workflow 5 (lint-development): Justification - The PR introduces a new pattern for implementing documentation lints by refactoring `doc_link_code` and `doc_paragraphs_missing_punctuation` into state machines that process events from a centralized markdown parser in `check_doc` (in `clippy_lints/src/doc/mod.rs`). This optimizes parsing (once per doc comment) and modularizes lint logic, impacting the documented lint implementation design in workflow 5. Evidence from PR changes to lint files and tests, matching relevant_files like \`clippy_lints/src/\` and \`tests/ui/\`.
5+
6+
No other workflows are affected, as changes are internal to specific lint implementations and do not alter scaffolding, registration, testing execution, or other high-level flows.
7+
8+
## Workflow 5 Analysis
9+
### Summary of design changes
10+
The PR affects the \`clippy_lints\` component, specifically the implementation pattern for documentation lints in \`src/doc/\`. Previously, \`doc_link_code\` logic was inline in \`mod.rs\` with its own event processing via \`check_for_code_clusters\`, and \`doc_paragraphs_missing_punctuation\` performed its own markdown parsing. The PR extracts \`doc_link_code\` to a new file with a \`LinkCode\` state machine struct and refactors the other to a \`MissingPunctuation\` state machine. These now process events from a single parsing in \`check_doc\`, called from the \`Documentation\` late lint pass via \`check_attrs\`.
11+
12+
This changes the design by introducing:
13+
- Centralized event generation to avoid redundant \`pulldown_cmark\` parsing.
14+
- Stateful, event-driven processing for modularity and efficiency.
15+
- Modular files for sub-lint logic within the doc module.
16+
17+
The PR implements this by updating \`mod.rs\` to instantiate the state machines and invoke their \`check\` methods in the event loop of \`check_doc\`, removing old redundant code. Benefits include performance improvement (single parse), easier maintenance, and a reusable pattern for future doc lints. Implications: Developers implementing new doc lints should follow this event-processing state machine pattern; the design doc for workflow 5 has been updated accordingly.
18+
19+
The affected diagram is the \"Integration and Execution Sequence Diagram\", where during \"execute lint passes during compilation phases\", for doc lints, the flow now includes event dispatching to state machines. Below is a diagram highlighting the differences in the doc lint processing sub-flow.
20+
21+
### Diagram showing changes
22+
```mermaid
23+
flowchart TD
24+
subgraph before[\"Before PR - Redundant Processing (to be removed)\"]
25+
Parse1[pulldown_cmark Parser in check_for_code_clusters]
26+
Parse2[pulldown_cmark Parser in doc_paragraphs_missing_punctuation::check]
27+
Inline[Inline state in mod.rs for doc_link_code]
28+
style Parse1 fill:#ffcccc,stroke:#ff0000
29+
style Parse2 fill:#ffcccc,stroke:#ff0000
30+
style Inline fill:#ffcccc,stroke:#ff0000
31+
end
32+
33+
subgraph changed[\"Modified - Central Dispatch (yellow)\"]
34+
CheckDoc[check_doc function in mod.rs]
35+
EventLoop[event loop over events]
36+
Dispatch[dispatches to state machines via .check(event)]
37+
style CheckDoc fill:#ffff99,stroke:#ffff00
38+
style EventLoop fill:#ffff99,stroke:#ffff00
39+
style Dispatch fill:#ffff99,stroke:#ffff00
40+
end
41+
42+
subgraph after[\"After PR - Additions (green)\"]
43+
SingleParse[single pulldown_cmark Parser in check_doc]
44+
SM1[LinkCode state machine - new file doc_link_code.rs]
45+
SM2[MissingPunctuation state machine - refactored file]
46+
Modul[Modular state accumulation across events]
47+
style SingleParse fill:#ccffcc,stroke:#00ff00
48+
style SM1 fill:#ccffcc,stroke:#00ff00
49+
style SM2 fill:#ccffcc,stroke:#00ff00
50+
style Modul fill:#ccffcc,stroke:#00ff00
51+
end
52+
53+
before -.->|replaced by| changed
54+
changed -.->|enhanced with| after
55+
56+
classDef removal fill:#ffcccc,stroke:#ff0000,stroke-width:2px
57+
classDef change fill:#ffff99,stroke:#ffff00,stroke-width:2px
58+
classDef addition fill:#ccffcc,stroke:#00ff00,stroke-width:2px
59+
```

0 commit comments

Comments
 (0)