Automattic / Automattic/harper

Support Go doc comment conventions by ignoring symbol names in comments

Open
#2,777 1 comment 1 reaction 0 assignees View on GitHub
enhancement harper-comments
Dominant language
Rust
Stars
15.4k
Forks
627
Avg merge
1d 12h
Merged PRs (30d)
106

Description

**What problem does this solve?**

In Go, the official convention is that documentation comments must start with the exact name of the symbol (package, function, type, or variable) being documented.
Because Harper currently treats these symbol names as standard English words, it results in a high volume of false positives (spelling and grammar errors) on almost every documented function in a Go codebase that use Go Doc extensively.

**Proposed Solution**

Harper should identify Go doc comments and treat the symbol names differently, so it isn't evaluated by spellchecking.

**Examples**

Function commentary, notice `HashStr` symbol name:

```go
// HashStr hashes a string and returns the hash using Foo algorithm.
func HashStr(p string) string {
// ...
}
```

Package commentary, notice `myalgo` package name following `Package` word:

```go
// Package myalgo provides handy algorithms.
package myalgo
```

Note: Go directives in comments (like //go:embed) seem to be handled correctly already by Harper.

**Component**

I don't know.

**Additional Context**

* Go Documentation Guidelines: Further information on the standard format can be found here: https://go.dev/blog/godoc

Contributor guide

Open the contributing guide

Research direction

Start by locating Harper's existing handling for Go directives, which the issue says already works, then trace how comments are evaluated for spelling and grammar. Add recognition for Go documentation comments so symbol names are ignored while surrounding prose continues to be checked, including function and package examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, rust
Domain
tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.