Go doc comments are classified as ordinary line comments, so no policy can keep them

[P4suta]

Reported from using ocomment on a Go repository whose rule is: ban every
comment except the licence header, tool directives, and a short doc comment.

The first two are expressible. The third is not, for two separate reasons.

1. Go doc comments are not recognised as doc comments

Rust distinguishes them and Go does not. Same shape, same run, --policy legal:

$ ocomment scan --policy legal docdemo.rs
docdemo.rs:1:1: doc-line remove 0..29: /// A doc comment on an item.
docdemo.rs:2:1: doc-line remove 30..70: /// Second line of the same doc comment.
docdemo.rs:5:1: line remove 89..112: // An ordinary comment.

$ ocomment scan --policy legal docdemo.go
docdemo.go:3:1: line remove 14..50: // Demo is a doc comment on an item.
docdemo.go:4:1: line remove 51..90: // Second line of the same doc comment.
docdemo.go:7:1: line remove 107..129: // an ordinary comment

the two files

/// A doc comment on an item.
/// Second line of the same doc comment.
pub fn demo() {}

// An ordinary comment.
pub fn other() {}

package demo

// Demo is a doc comment on an item.
// Second line of the same doc comment.
func Demo() {}

// an ordinary comment
func other() {}

--policy safe says it "Remove ordinary and doc comments", and keep_kind /
remove_kind are per kind, so the distinction is the intended axis — it just is
not observable for Go. Go has no ///: a doc comment is an ordinary // run
that is attached to a declaration, with only a blank line or a non-comment
line separating it from one. That is a parse-position property rather than a
token-syntax one, which is presumably why it was not picked up.

The same is true of Python (a docstring is a string expression in a specific
position), and of C and C++ where /** */ and /// are conventions rather than
grammar.

2. A policy cannot say how long a comment may be

A Go doc comment of ten lines is ten line tokens with nothing tying them
together, so even with kind detection there is no way to write "a doc comment of
at most one line". keep_regex matches one token at a time and cannot count the
group.

A max_lines (or max_bytes) bound on a kept kind would close it:

[policy]
mode = "legal"
keep_kind = ["directive", "doc"]

[policy.doc]
max_lines = 1

What I did instead

Kept ocomment --policy legal for every file that is not Go, and wrote a
bespoke Go AST gate for the Go files: a comment is allowed if it is the SPDX
header, a directive, or a doc comment of one line. That gate is ~60 lines and it
is the part I would rather not own, because the interesting half — knowing what
a comment is — is what ocomment already does for ten other languages.

Versions

ocomment 0.1.0, macOS 27, on a repository of 1049 scanned files.