I've written a linter / code formatter / auto bug repair tool internally for my current company and it sucked. Still sucks. Comments doubly so.
The examples are few, undocumented, and don't always work with the vendor directory concept.
I had to write my own custom importer to get vendor support to be more reliable.
I like the concept of shipping with an AST package; it's very forward looking and useful.
I too hope the go/analysis package could be the answer. I believe it has not merged but has a prototype version that conflicts with master. Maybe they'll patch it up and get it landed soon. I hope, anyways
For manipulating code tho (e.g. for code gen or rewriting), yeah - absurdly unfriendly fits pretty well, and comments only kinda sorta mostly work until you actually try to produce anything polished. It kinda feels like they prioritized forward-compatibility at the cost of usability (which could be a decent decision / a fair tradeoff, but it sucks as a user trying to do stuff now).
There's a semi-recent experiment to try to make a pluggable lint system[3], but I'm not sure what the current status is.
For my workplace, tbh I plan on making something semi-hacky just to get us off the ground + use real go plugins so we actually have some minor extensibility without reams of boilerplate. I've built several tiny things that just use the AST (which is not bad at all, and quite fast - several thousand source files take about 250ms), and they've been worth the effort like 100x over, but it's hard / impossible to do anything better without the type checker + significant amounts of work.
[1]: very highly recommended, it has far more / better checks than others I've seen, but is also quite slow and hard to extend: https://staticcheck.io/
[2]: it's honestly quite a good repo, but there needs to be more. it's a fairly unfriendly API and there are few helper libs as far as I've seen: https://golang.org/s/types-tutorial
[3]: https://docs.google.com/document/d/1-azPLXaLgTCKeKDNg0HVMq2o...