fix: detach file comments from package declaration

[ardnew]

The lexer source file auto-generated by cmd/participle outputs the package declaration immediately after:

1. the DO NOT EDIT comment recognized by Go tools, and

   // Code generated by Participle. DO NOT EDIT. package foo 

2. (optional) a compiler directive containing build constraints.

   // Code generated by Participle. DO NOT EDIT. //go:build ... package foo 

In both cases, many linters/analyzers end up attaching the comment line (but not the constraints directive) to the package clause as its documentation. This is then flagged as improper grammar in some way.

For example, staticcheck raises a warning (ST1000):

package comment should be of the form "Package foo..."

The best official guidance I can find to support the proposed change comes from go help buildconstraint, which states:

To distinguish build constraints from package documentation,
a build constraint should be followed by a blank line.

With this change applied, the resulting output includes a single line break between the build constraint and package declaration:

// Code generated by Participle. DO NOT EDIT. //go:build ... package case2 

Both GitHub Copilot and Google's AI Mode suggest adding another line break between the comment and directive:

// Code generated by Participle. DO NOT EDIT. //go:build ... package case2 

But I can't find any Go documentation recommending this.

---

Currently, there isn't any way to actually add a package comment to the generated source file. It would be neat if cmd/participle accepted a flag that would insert a comment between the proposed line break and package declaration, e.g.:

$ participle gen lexer --name Foo --comment "Package foo bars." foo 

// Code generated by Participle. DO NOT EDIT. // Package foo bars. package foo 

[Copilot]

Pull Request Overview

This PR ensures a blank line is emitted between the generated‐file comment/build constraint and the package declaration to prevent linters from mis-associating the comment as package documentation.

• Changed the template’s {{end -}} to {{end}} and added an explicit blank line
• Always emit a newline before package {{.Package}}, regardless of .Tags

Comments suppressed due to low confidence (2)

cmd/participle/codegen.go.tmpl:1

• Consider adding a unit test that renders this template with and without .Tags to verify the blank line appears correctly in both cases.

// Code generated by Participle. DO NOT EDIT. 

[alecthomas]

Thanks!