Automattic / Automattic/harper

Ignore code in document blocks

Open
#1,440 4 comments 1 reaction 0 assignees View on GitHub
enhancement
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:

![Image](https://github.com/user-attachments/assets/11616e66-c837-447c-ac1f-d89c604b57cc)

```
#
# 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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.