Skip to content

doc: improve example coverage #16360

Closed
Closed
@ucirello

Description

@ucirello

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.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions