Hi Team, I'm the author of godoc-lint, and discovered this repo thanks to @julieqiu's valuable feedback (See this issue). Super excited that the linter is helping out here 🚀, and that's why I felt responsible to share some thoughts to enhance the experience and also to prevent you from any potential headaches down the road.

Here are a couple of things I wanted to highlight:

1. The issue mentioned above is now fixed, and I think you can now have an idiomatic godoc for the main package (at cmd/librarian/main.go) without the need to exclude the path from the linter. I tested this change on my clone of googleapis/librarian and it seems working. Kudos to @julieqiu for reporting this! 🙏

2. Since the linter is still in its v0 days 🍼, I recommend pinning it at v0.3.0 (current latest) to safeguard the project against any future breaking changes. I always tend to keep it backwards compatible, but still it's v0. That said, I'll ping you folks in the future about new features that might be interested for you.

3. I noticed the TestExportedSymbolsHaveDocs function in all_test.go ensures all exported symbols (except consts) have godocs. Godoc-Lint can help you with this as well if the require-doc rule is enabled. When this rule is enabled, the linter will check that exported symbols (excluding tests) have godoc (regardless of the format/phrasing). You just need to call the linter like this:

   go run github.com/godoc-lint/godoc-lint/cmd/[email protected] -enable require-doc -exclude '\.pb\.go$' -exclude 'internal/sidekick' ./...

   Just note that:

   • This has to be a separate call; i.e. not to be mixed with the one used in TestGodocLint since the exclusions are just meant to be made for the require-doc rule.
   • It will also check const declarations which is not already covered in TestExportedSymbolsHaveDocs. However, as I checked the test passes since all exported consts have godocs, and it seems like a good idea to me to include them in the check.

All said, I'll be thrilled to contribute to googleapis/librarian if you see value in any of the suggestion above.