cayley
cayley copied to clipboard
cayleygraph
Documentation
This is a catchall issue.
As highlighted in #91, a significant proportion of the exported codebase lacks doc comments or the comments are not associated with the relevant labels according to the godoc conventions (and so are missed by golint and godoc).
It might be worth considering adding a page to the wiki on graph databases in general (and links to resources). This kind of approach to client education has been very successful in growing the Go userbase with the {talks,blog}.golang.org pages and the go-tour.
I love to help add docs to code but don't know about GoDoc. Here are some References on how to write GoDoc. [0] Intro for Pythonistas. http://golang-for-python-programmers.readthedocs.org/en/latest/doc.html [1] Possibly the most complete tutorial, this item originated as blog post and became a git repo with working examples. http://blog.natefinch.com/2014/04/effective-godoc.html https://github.com/natefinch/godocgo https://godoc.org/code.google.com/p/go.tools/cmd/godoc [2] One pager with examples and tips. https://godoc.org/github.com/fluhus/godoc-tricks [3] Docs for test, eg if write documentation tests. http://golang.org/pkg/testing/ [4] Other posts. http://blog.golang.org/godoc-documenting-go-code http://www.goinggo.net/2013/06/documenting-go-code-with-godoc.html [5] Git commit of updating some docs per godoc standards. https://gitorious.org/marc21-go/marc21/commit/f4f00cdfb56d32e6e196b565bd215245e3c0fd97 [6] No official full docs exist per my research. [7] Free EBook on Go. http://www.golangbootcamp.com/ // AnneTheAgile , here and there via CodeTriage.com
@AnneTheAgile Would love the help! The GoDoc bit is one thing for sure, but there's regular documentation that could use some help from writers too. An exposition on getting started, using Visualize, etc, within docs/ would be great too! (Overview.md is there but it could always use help)
To extend on this; doc comments can be refined into good godoc during review. Just picking a package and adding doc comments to exported functions, types and methods (and the package decl) is a start in this process.
As a tip, running an instance of godoc started by godoc -http=:6060 and reviewing your rendered documentation in the browser is a good way of both writing nice documentation and learning how to use the godoc system.