package-comments flags main as of 1.2.2

[twmb]

This might not be a bug, but I'd like to clarify if this is intentional. It's not common to document main packages, I personally plan to disable the rule if it continues to lint documenting main.

[chavacava]

Hi @twmb, thanks for filling the issue.

Well, even if documenting main packages might be not so common, the official guideline for documenting GO code says they should be documented:

Every package should have a package comment introducing the package.

and it also provides an example for a main package:

/*
Gofmt formats Go programs.
It uses tabs for indentation and blanks for alignment.
Alignment assumes that an editor is using a fixed-width font.
[...]
When gofmt reads from standard input, [...]
formatted by piping them through gofmt.
*/
package main

As a reference, standard GO tools have documented main packages.

Must revive lint main package documentation? I think it must but I'm open to discuss about.

[hawkingrei]

We have meet this problem, too. but we are not main package.

pingcap/tidb#37413

https://ci.pingcap.net/blue/organizations/jenkins/tidb_ghpr_build/detail/tidb_ghpr_build/78196/pipeline

util/texttree/texttree.go:15:1: package-comments: should have a package comment (revive)

https://github.com/pingcap/tidb/blob/a80078538d366d55acfc34dd772b1977a720a9bc/util/texttree/texttree.go#L14-L16

[twmb]

Must revive lint main package documentation?

I'm open to it, but I think it's worth a quick survey of the packages that already use revive to see if they currently document main. I never have -- I document my main packages elsewhere. As well, main packages do not follow the common Package main ..., as seen in the linked post above.

[chavacava]

We have meet this problem, too. but we are not main package.

util/texttree/texttree.go:15:1: package-comments: should have a package comment (revive)

https://github.com/pingcap/tidb/blob/a80078538d366d55acfc34dd772b1977a720a9bc/util/texttree/texttree.go#L14-L16

Hi @hawkingrei , I've checked the code you point in your comment and I've seen there is no documentation for the texttree package. Thus revive pointing that lack of documentation seems OK to me. Do you agree or I'm missing something?

[chavacava]

As well, main packages do not follow the common Package main ..., as seen in the linked post above.

Yes, revive takes that into account

[mcandre]

A package level API doc for a main package may seem like overkill.

However, projects that provide multiple applications can use the separate docs to explain the purpose of each application.

For example:

// Package main implements a GIF editor application.
package main

Even a Go project with only one application, can still use this API doc to encourage the author to say a few words about the purpose of their application. There are tons of projects, FOSS and enterprise, with zero explanation for their tools are intended to accomplish.

The developer describing a project in the package main API doc, and the README, and the repository slug, enjoys multiple opportunities to attempt to communicate, using different descriptions for each of these snippets. The coder is often so deeply immersed in their project that they forget: The wider world has no idea how to install their widget, how to run it, or what their widget is supposed to do. But each individual attempt at communication raises the odds of successfully gaining an audience.