I have created this topic so that we can divide work to write documentation for our packages. I am taking up writing documentation for
You guys can pick up other packages. I plan to work on this after completing the bug fixes assigned to me. I would recommend you guys to run golint, govet for the packages you take up and then fix things that you find relevant.
Also, read https://blog.golang.org/godoc-documenting-go-code.
I can take up these:
Regarding documentation as discussed on Friday, while godoc only enforces documentation for Exported functions and variables, we should also add comments for internal functions as applicable as this is aimed towards contributors and there are many important functions that aren’t exported (Example: processTask isn’t exported, but a comment would help dgraph/task.go at master · dgraph-io/dgraph · GitHub).
Godoc is mainly aimed towards libraries which give details on which functions developers can call and provide information on it. The reason we are documenting is for understanding the code and not for use as a library. So, we should extend the documentation to unexported functions and variables where applicable.
Good point @ashwin95r. I think it makes sense to document unexported functions and variables as most our documentation would be consumed by other developers. Also, the code inside functions could do well with a bit more documentation.
This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.