Hacker News Reader

Comment by throwawaylala1 | Hacker News Reader

> The best way would be exporting docs from your codebase, and have all documentation related artifacts expressed alongside the code

I LOVE Golang's approach to this [1]:

- Documentation generation from code is built in to the language toolkit

- There is a standard for writing the comments so all of them look the same across every project

- It even supports code examples which are visible as a REPL in the generated docs

When people ask "what's so great about Go?". It's stuff like that which is hard to succinctly describe but makes a huge difference in overall quality of Go code in the wild.

[1]: https://go.dev/doc/comment

View on HN

So basically what Common Lisp, Smalltalk, Java, Perl, Python and Ruby have provided before Go was a thing.

Many of the Go features are only a win when the competition is C.

I can’t speak for the others, but Godoc is IME way better than JavaDoc, which is both hard to write, and hard to read inline due to all the f*ing HTML.

More to the point, just because some platforms provide equivalent functionality doesn’t make the GP wrong.

A nice Javadoc touch that Golang could use is to break out the documentation of arguments and return values.

So here's an example of the string package: https://pkg.go.dev/strings

In what way would the JavaDoc @param/@return/etc annotations actually help? What Godoc has is more than suitable for the vast majority of cases.

They provide the parsing engine with better clues for the AST that is given to the JavaDoc agent (aka doclet), which allows to customize the document generation process.

Which didn't answer my question at all. Adding more structure to the AST with @param/@return/whatever doesn't make for better documentation. It's useless crap in a real world scenario.

Let me guess, another ACME fan that like Rob Pike doesn't use anything fancy as editor, including syntax highlighting.

That crap allows for tooling that Go will never have thanks community culture.

I use VIM and didn't even know ACME editor existed.

Keep building strawmen, I'll be building software.

With respect, the general level of day-to-day tooling for Go is way better than for Java. Go is designed to be easy to parse and easy to build tooling for.

“That crap” is at least in part a reaction to the endless stream of DocTagFactoryFactoryFactories patterns that came out of the Java world. While I think Java is a decent language with a good ecosystem, I’m completely over the idea that the only way to do things is the Java Enterprise(tm) way.

Have you seen the IDEs that show that documentation for the variables due to the position they take on the function call?

What is on that documentation site you linked is just a text formatting guide, it's absolutely not enough to get a powerful documentation system. But yeah, it's simple.

I have. My editor also gives me documentation for every function that I need. Plain text is more than enough for that use.

What kind of function documentation are you reading inline lol? Does it have like 30 function arguments?

This is why I said it's hard to succinctly explain. Non-programmers and bad programmers can't tell the difference between Go and Python (for example) in this context. The actual difference is very very significant.

Reply on news.ycombinator.com