Automattic / Automattic/harper
Support Go doc comment conventions by ignoring symbol names in 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
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