Skip to content

doc: improve example coverage #16360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
19 tasks done
ucirello opened this issue Jul 13, 2016 · 28 comments
Closed
19 tasks done

doc: improve example coverage #16360

ucirello opened this issue Jul 13, 2016 · 28 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge help wanted
Milestone
Unreleased

Comments

@ucirello
Copy link
Contributor

ucirello commented Jul 13, 2016 •
edited
Loading

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
@adg adg added this to the Unreleased milestone Jul 19, 2016
@adg
Copy link
Contributor

adg commented Jul 19, 2016

Looks great to me. Added the 'Unplanned' milestone because these are not tied to a specific release. Added the 'HelpWanted' label as this is something anyone can work on.

Thanks for the list!

@ucirello
Copy link
Contributor Author

Welcome - I'm going to start working on at least few of them.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/25173 mentions this issue.

@dsnet dsnet mentioned this issue Jul 28, 2016
Closed
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/25575 mentions this issue.

@josharian josharian added the Documentation Issues describing a change to documentation. label Aug 10, 2016
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/26696 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/26697 mentions this issue.

gopherbot pushed a commit that referenced this issue Aug 16, 2016
@ucirello @adg
bytes: add examples
14e446d 
`bytes` and `strings` are pretty similar to each other, this commit
brings `strings` examples to its counter-part.

Partially addresses #16360

Change-Id: I551320eaa78be9df69012035f1c3333f500e04c9
Reviewed-on: https://go-review.googlesource.com/25062
Reviewed-by: Andrew Gerrand <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
@cespare cespare mentioned this issue Aug 17, 2016
Closed
@RobbieMcKinstry
Copy link

Hi! I'd love to contribute to this. Is there anything in particular you would like home @ccirello? :)

@ucirello
Copy link
Contributor Author

@RobbieMcKinstry contributions are always welcome. I suggest you looking for the package you care most or is most knowledgeable about and start with it. If you find something that's not in the list above, it won't be a problem - go ahead and work on it.

@kavirajk
Copy link
Contributor

@ccirello Great idea. I'd love to contribute whatever I can. +1

@jnmoal jnmoal mentioned this issue Aug 18, 2016
Closed
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/27398 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/27433 mentions this issue.

gopherbot pushed a commit that referenced this issue Aug 21, 2016
@kostya-sh @bradfitz
index/suffixarray: add Lookup example
94d9cc7 
Updates #16360

Change-Id: Idd8523b5a9a496ebd9c6e3b89c30df539842a139
Reviewed-on: https://go-review.googlesource.com/27433
Reviewed-by: C Cirello <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/27443 mentions this issue.

gopherbot pushed a commit that referenced this issue Aug 22, 2016
@wlynch @bradfitz
net/http/httptrace: add simple example and fix copyright header
4187e1f 
Partially addresses #16360

Change-Id: I67a328302d7d91231f348d934e4232fcb844830a
Reviewed-on: https://go-review.googlesource.com/27398
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
@ceocoder ceocoder mentioned this issue Aug 25, 2016
Closed
ceocoder pushed a commit to ceocoder/go that referenced this issue Aug 27, 2016
@dhaivat
net/http/cookiejar: added simple example test
372d471 
Partially fixes golang#16360

Change-Id: I01563031a1c105e54499134eed4789f6219f41ec
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/27993 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/26930 mentions this issue.

gopherbot pushed a commit that referenced this issue Aug 29, 2016
@ucirello @bradfitz
mime/quotedprintable: add examples
650c2c1 
Partially addresses #16360

Change-Id: Ic098d2c465742fb50aee325a3fd0e1d50b7b3c99
Reviewed-on: https://go-review.googlesource.com/25575
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/28482 mentions this issue.

gopherbot pushed a commit that referenced this issue Sep 8, 2016
@ALTree @bradfitz
go/format: add format.Node example
b6f4492 
Updates #16360

Change-Id: I5927cffa961cd85539a3ba9606b116c5996d1096
Reviewed-on: https://go-review.googlesource.com/26696
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
gopherbot pushed a commit that referenced this issue Sep 8, 2016
@odeke-em @bradfitz
encoding/hex: implement examples using all exported functions
141f1a0 
Fixes #11254.
Updates #16360.

Implements examples using all exported functions.

This CL also updates Decode documentation to
state that only hexadecimal characters are accepted
in the source slice src, but also that the length
of src must be even.

Change-Id: Id016a4ba814f940cd300f26581fb4b9d2aded306
Reviewed-on: https://go-review.googlesource.com/28482
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
gopherbot pushed a commit that referenced this issue Sep 9, 2016
@dhaivat @bradfitz
net/http/cookiejar: added simple example test
57d4e57 
Fixes #16884
Updates #16360

Change-Id: I01563031a1c105e54499134eed4789f6219f41ec
Reviewed-on: https://go-review.googlesource.com/27993
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
gopherbot pushed a commit that referenced this issue Sep 9, 2016
@ucirello @bradfitz
context: add examples
1161a19 
Add function level examples to the package.

Partially addresses #16360

Change-Id: I7162aed4e4a969743c19b79c9ffaf9217d2c1c08
Reviewed-on: https://go-review.googlesource.com/26930
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/28992 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/28963 mentions this issue.

gopherbot pushed a commit that referenced this issue Sep 14, 2016
@odeke-em @adg
os: add more examples
33e63eb 
Updates #16360.

Adds examples for:
+ Chmod
+ Chtimes
+ FileMode

Change-Id: I1b61ee0392fa3774593a7f36aaf0fa1e484c778b
Reviewed-on: https://go-review.googlesource.com/28963
Run-TryBot: Andrew Gerrand <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Andrew Gerrand <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/29150 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/29218 mentions this issue.

gopherbot pushed a commit that referenced this issue Sep 16, 2016
@odeke-em @adg
os/exec: add examples for CombinedOutput, StdinPipe, StderrPipe
c55c33a 
Updates #16360.

Adds examples for:
+ CombinedOutput
+ StdinPipe
+ StderrPipe

Change-Id: I19293e64b34ed9268da00e0519173a73bfbc2c10
Reviewed-on: https://go-review.googlesource.com/29150
Run-TryBot: Andrew Gerrand <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Andrew Gerrand <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/29375 mentions this issue.

gopherbot pushed a commit that referenced this issue Sep 19, 2016
@odeke-em @bradfitz
crypto/md5, crypto/sha1, crypto/sha256: add examples for checksumming…
31ba855 
… a file

Updates #16360.

Change-Id: I75714d2b5f095fe39fd81edfa6dd9e44d7c44da1
Reviewed-on: https://go-review.googlesource.com/29375
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/29443 mentions this issue.

gopherbot pushed a commit that referenced this issue Sep 21, 2016
@bradfitz
image/draw: add FloydSteinberg Drawer example
16f81b6 
Updates #16360

Change-Id: I80b981aa291a8e16d2986d4a2dfd84d3819bf488
Reviewed-on: https://go-review.googlesource.com/29443
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Joe Tsai <[email protected]>
gopherbot pushed a commit that referenced this issue Sep 21, 2016
@suyash @bradfitz
image/png: add Encode and Decode examples
445f51f 
partially addresses #16360

Change-Id: I8274825b9ca6aec46294c8513b4795b0eb3062a2
Reviewed-on: https://go-review.googlesource.com/28992
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
gopherbot pushed a commit that referenced this issue Sep 22, 2016
@odeke-em @bradfitz
compress/gzip: add examples
dcbbd31 
Updates #16360.

Adds examples uing:
+ Writer, Reader
+ Reader.Multistream to concatenate and then
individually retrieve multiple gzipped files
+ Reset

Change-Id: I9ad9b92729a5cd58f7368eaf2db05f1cdf21063d
Reviewed-on: https://go-review.googlesource.com/29218
Reviewed-by: Brad Fitzpatrick <[email protected]>
Reviewed-by: Joe Tsai <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/29611 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/30162 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/30103 mentions this issue.

gopherbot pushed a commit that referenced this issue Oct 5, 2016
@alexd765 @bradfitz
os/exec: add example for CommandContext
a9b4953 
Updates #16360

Change-Id: I0e0afe7a89f2ebcb3e5bbc345f77a605d3afc398
Reviewed-on: https://go-review.googlesource.com/30103
Reviewed-by: Brad Fitzpatrick <[email protected]>
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/30554 mentions this issue.

gopherbot pushed a commit that referenced this issue Oct 6, 2016
@alexd765 @bradfitz
math/cmplx: add examples for Abs, Exp, Polar
7b4a224 
Updates #16360

Change-Id: I941519981ff5bda3a113e14fa6be718eb4d2bf83
Reviewed-on: https://go-review.googlesource.com/30554
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
gopherbot pushed a commit that referenced this issue Oct 12, 2016
@jnmoal @bradfitz
os: add examples of environment functions
6d702d8 
For #16360.

Change-Id: Iaa3548704786018eacec530f7a907b976fa532fe
Reviewed-on: https://go-review.googlesource.com/27443
Run-TryBot: Russ Cox <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/31137 mentions this issue.

@bradfitz
Copy link
Contributor

There have been a ton of examples added to tip (for Go 1.8) so far. I'm very happy about this.

That said, I think we should take a break for the next few months, until the Go 1.9 cycle opens up again. There's a shortage of reviewer time at the moment and I'd like everybody to focus on open bugs instead of example documentation reviews.

@ucirello
Copy link
Contributor Author

Makes sense. I am going to update the list with the completed work, and move away with what's not done yet, and close the issue. We can always open a new issue with a newer up to date list during Go1.9 cycle

gopherbot pushed a commit that referenced this issue Oct 17, 2016
@groob @bradfitz
encoding/pem: add Decode example
b97b753 
For #16360.

Change-Id: I99d1e5ab1f814f65b3066a498158a442f1bd477f
Reviewed-on: https://go-review.googlesource.com/31137
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
gopherbot pushed a commit that referenced this issue Nov 3, 2016
@odeke-em @adg
encoding/json: example on MarshalJSON, UnmarshalJSON
2b59b15 
Updates #16360.

Change-Id: I5bf13d3367e68c5d8435f6ef2161d5a74cc747a7
Reviewed-on: https://go-review.googlesource.com/29611
Reviewed-by: Andrew Gerrand <[email protected]>
Run-TryBot: Andrew Gerrand <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
gopherbot pushed a commit that referenced this issue Nov 12, 2016
@dsnet
compress/flate: add examples
091ba60 
Updates #16360

Change-Id: I66ff23e0501363f58fe891d5e95806422071f93b
Reviewed-on: https://go-review.googlesource.com/30162
Run-TryBot: Brad Fitzpatrick <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
@golang golang locked and limited conversation to collaborators Oct 17, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge help wanted
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
7 participants
@bradfitz @josharian @ucirello @kavirajk @RobbieMcKinstry @adg @gopherbot