Description
I'd like to resume expanding the documentation with more examples. After some discussion offline and previous experiences, such 17295 and 13926, I have mapped potential packages that could use some work on example in documentation.
Also, I'd like to suggest some aspirational guidelines about how far should an example go:
1 - Examples should be able to convey the intention of the package or some subset of its interface. Or, in other terms, intention revealing package or type level examples are preferred over function level examples. Exception being, of course, functions whose functionality are entirely self-contained, e.g. crypto/sha1.Sum.
2 - The goal for examples is to reveal intention first; to be a reusable snippet of code later second. I am not sure how to phrase this, but in the end, we do not want to promote a copy'n'paste culture out of the documentation.
3 - In the process of adding examples, perhaps add link to wiki, blog or external resources to help novices to bridge occasional lack of context.
4 - Be careful in not inducing abstraction decisions in the process of making easy examples - prefer simple examples over easy ones.
I think it is a good idea to open issues for each one of these packages, and discuss them individually. Not all of them are missing examples, but could have a more complete set.
- compress/flate (30162)
- encoding/json (29611)
- bytes (25062)
- compress/bzip2 (25173)
- compress/gzip (29218)
- context (26930 27405)
- crypto/md5 (29375)
- crypto/sha1 (29375)
- crypto/sha256 (29375)
- encoding/hex (28482 and encoding/hex: Suggestions for doc improvements #11254)
- encoding/pem (31137)
- go/format (26696)
- image/draw (29443)
- image/png (28992)
- index/suffixarray (27433)
- math/cmplx (30554)
- mime/quotedprintable (25575)
- net/http/cookiejar (27993)
- net/http/httptrace (27398)
- os (27443 27996 25571 28963)
- os/exec (29150)
Edit: Removed packages that have not been worked. Let's focus fixing bugs on this cycle and resume example efforts for Go1.9 cycle.
- compress/lzw
- encoding/ascii85
- encoding/asn1
- expvar
- fmt
- hash/adler32
- hash/crc64
- hash/fnv
- image/color
- image/color/palette
- image/gif
- image/jpeg
- math
- net/http/cgi
- net/http/pprof
- net/rpc
- net/rpc/jsonrpc
- net/textproto
- os/user
- regexp/syntax
- testing/iotest
- testing/quick
- unicode/utf16
//cc: @adg