search

antlr / antlr4

ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.
http://antlr.org
BSD 3-Clause "New" or "Revised" License
16.88k stars 3.25k forks source link

Go Target Code Should Use Godoc-Style Inline Docs #1374

Open ereyes01 opened 7 years ago

ereyes01 commented 7 years ago

I'm new to ANTLR and I've been having fun all night with the new Go target, thanks for that!

I've been perusing some of the Go source trying to learn the API of the generated Go code, and I noticed that some functions are documented with what appears to be Javadoc style comments. The standard in Go is to use Godoc-style comments, and the Go linter will complain when exported fields / functions do not have a Godoc comment.

Also, having Godocs gives the free benefit of a nice doc webpage that is autogenerated for any go-gettable repository via godoc.org. Here's what the current ANTLR Go code looks like in godoc.org.

All that being said, I understand it's possible that ANTLR has a project-wide policy of thou shalt use Javadoc that supercedes the language's idiom... up to the maintainers I guess.

parrt commented 7 years ago

godoc would be best for go target. feel like fixing it? ;)

ereyes01 commented 7 years ago

I'd be happy to switch the existing javadoc-style ones when I get some time soon... However, for the many undocumented exported functions, someone who actually knows what they're doing with ANTLR would probably write better docs than I :-)

jimidle commented 2 years ago

I will gradually improve this over time.