Automattic / Automattic/harper
Ignore code in document blocks
- Dominant language
- Rust
- Stars
- 15.4k
- Forks
- 627
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 102
Description
## Description
Harper should ignore "code reference" in document blocks such as YARD (Ruby) and JSdoc (Javascript).
## Component
- Core grammar checking engine
## Use Cases
Here is an example of code being marked as invalid:

```
#
# Deletes old Relational Analytics data
#
# Any data older than the cutoff is deleted from the duckdb database
#
# @param cutoff [ActiveSupport::TimeWithZone] 3.years.ago.midnight by default
#
# @raise [RuntimeError] if no database file has been prepared.
# @raise [RuntimeError] if an unsupported revision is encountered.
#
# @return [Boolean]
```
## Implementation Ideas
- It should identify common code documentation blocks, such as YARD (Ruby) and JSdoc (Javascript).
- For YARD I think the identification could be as simple as: for any line starting with `# @`, ignore anything in brackets (`[]`)
- Ideally it should also ignore anything in backtics, such as "MyModel" in `# Calling into ``MyModel`` to resolve the actual user.`
Contributor guide
Research direction
Start with the core grammar checking engine and trace how document blocks are tokenized and checked. Compare the requested YARD and JSDoc cases, including bracketed and backticked code references; done means those references are ignored without suppressing ordinary prose grammar checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, ruby, rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100