Documenting packages

When we created our even package, we skipped over an important item:documentation. Each package should have a package comment, a block commentpreceding the package clause. In our case we should extend the beginning ofthe package, with:

  1. // The even package implements a fast function for detecting if an integer
  2. // is even or not.
  3. package even

When running go doc this will show up at the top of the page. When a packageconsists of multiple files the package comment should only appear in onefile. A common convention (in really big packages) is to have a separatedoc.go that only holds the package comment. Here is a snippet from theofficial regexp package:

  1. /*
  2.     The regexp package implements a simple library for
  3.     regular expressions.
  5.     The syntax of the regular expressions accepted is:
  7.     regexp:
  8.         concatenation { '|' concatenation }
  9. */
  10. package regexp

Each defined (and exported) function should have a small line of textdocumenting the behavior of the function. Again to extend our even package:

  1. // Even returns true of i is even. Otherwise false is returned.
  2. func Even(i int) bool {

And even though odd is not exported, it’s good form to document it as well.

  1. // odd is the opposite of Even.
  2. func odd(i int) bool {