Hacker News Reader

Comment by sergiotapia | Hacker News Reader

Speaking of documentation... I'm starting work on my first Go library and I want to make sure I'm not fighting against the ecosystem.

https://github.com/sergiotapia/smitego

How do go programmers write their documentation? Do I just write comments on func's and use a tool to generate it? What the standard?

Thanks

View on HN

See http://blog.golang.org/godoc-documenting-go-code for Go documentation guidelines. Use the godoc tool included with the Go distribution to read package documentation locally. Use godoc.org to view documentation on the web. The documentation for your package is at http://godoc.org/github.com/sergiotapia/smitego .

Most languages now have a tool for writing and hosting documentation to make this as easy as possible for you. The author of the post runs http://readthedocs.org/, which is primarily used by Python developers, for instance.

For Go, the standard toolchain is the builtin go doc tool (http://godoc.org/code.google.com/p/go.tools/cmd/godoc), and the GoDoc website for hosting (https://godoc.org/-/about). Using that pair of tools will be a good start.

The advantage of these standardised tools is that it gives most documentation for projects in a given language a common 'look'. Go libraries have one kind of appearance, Python ones another, and so on. This tends to make navigating around much easier.

However, Sphinx & Read the Docs is not just for Python :)

http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-fo...

I created a website that automatically generates documentation and examples for libraries in Go (and Python, Ruby, and JavaScript). Here's your project on it:

https://sourcegraph.com/github.com/sergiotapia/smitego

For Go, godoc.org is also great.

Reply on news.ycombinator.com