blob: b160c6c95e2c2a5c5b69748848fcd42b9873c023 [file] [log] [blame]
Go docs
Golang-Syd, Oct 17, 2012
Rob Pike
Google, Inc.
@rob_pike
http://golang.org/s/plusrob
http://golang.org
* Documentation
* Text
There are many ways to show documentation as text
* Man pages: Unix 1st Edition, 1971
.image go-docs/seek.png
* Man pages: Apple OS X 10.8, 2012
.image go-docs/lseek.png
* Javadoc 1996+
.image go-docs/javadoc.png
* Javadoc 1996+
.image go-docs/javadoc1.png
* Godoc 2009+
.image go-docs/godoc.png
* Godoc 2009+
.image go-docs/godoc1.png
* Godoc
.link http://golang.org/pkg/utf16
* blog.golang.org
.image go-docs/blog.png
* Code walks
.image go-docs/codewalk.png
* Community contributions
* Go wiki
.link http://golang.org/wiki
.image go-docs/gowiki.png
* Gopkgdoc
.link http://go.pkgdoc.org
.image go-docs/gopkgdoc.png
* Gopkgdoc
.link http://go.pkgdoc.org/code.google.com/p/goauth2/oauth
* Go By Example
.link https://gobyexample.com
.image go-docs/gobyexample.png
* Go By Example
.link https://gobyexample.com/timeouts
* Talks
* Presentations
We give a lot of talks.
Most of the tools for presentations focus on style, not ease of creation.
* Present
In the `go.talks` repo, have a new tool: `present`.
go get code.google.com/p/go.talks/present
- Simple
- Easy to use
- Easy, smooth to present
Took about an hour to put this talk together.
Docs:
.link http://go.pkgdoc.org/code.google.com/p/go.talks/present
* Input for the previous slide
.code go-docs.slide /^\* Present$/,/^\.link/
* Input for the previous slide redux
.code go-docs.slide /^\*.*previous/,/^\.code/
* Revenge of the input for the the previous slide
.code go-docs.slide /^\*.*redux/,/^\.code/
* Many choices
Lots of presentations, different styles.
* Fatal flaw
They all have code.
Can't execute the code!
Want to edit and play.
* The playground
.image go-docs/play.png
* Can run code from the browser
.link http://play.golang.org
* The tour
.image go-docs/tour.png
* Can run code from the browser
.link http://tour.golang.org
* Use this technology
Want to embed the playground technology in the other media.
Triggering example: Go Concurrency Patterns, Google I/O, 2012
Needed to demonstrate concurrency and the passage of time.
* Go Concurrency Patterns
An extract from the talk.
* Multiplexing
These programs make Joe and Ann count in lockstep.
We can instead use a fan-in function to let whosoever is ready talk.
.code go-docs/faninboring.go /START3/,/STOP3/
.play go-docs/faninboring.go /START1/,/STOP1/
* .code and .play
Input for the previous slide:
.code go-docs.slide /^\* Multiplexing/,/^.play/
* faninboring.go (I)
package main
import (
"fmt"
"math/rand"
"time"
)
// START1 OMIT
func main() {
c := fanIn(boring("Joe"), boring("Ann")) // HL
for i := 0; i < 10; i++ {
fmt.Println(<-c) // HL
}
fmt.Println("You're both boring; I'm leaving.")
}
// STOP1 OMIT
* faninboring.go (II)
// START2 OMIT
func boring(msg string) <-chan string { // Returns receive-only channel of strings. // HL
c := make(chan string)
go func() { // We launch the goroutine from inside the function. // HL
for i := 0; ; i++ {
c <- fmt.Sprintf("%s: %d", msg, i)
time.Sleep(time.Duration(rand.Intn(2e3)) * time.Millisecond)
}
}()
return c // Return the channel to the caller. // HL
}
// STOP2 OMIT
// START3 OMIT
func fanIn(input1, input2 <-chan string) <-chan string { // HL
c := make(chan string)
go func() { for { c <- <-input1 } }() // HL
go func() { for { c <- <-input2 } }() // HL
return c
}
// STOP3 OMIT
* .code and .play again
The input for the Multiplexing slide again:
.code go-docs.slide /^\* Multiplexing/,/^.play/
* Multiplexing again
These programs make Joe and Ann count in lockstep.
We can instead use a fan-in function to let whosoever is ready talk.
.code go-docs/faninboring.go /START3/,/STOP3/
.play go-docs/faninboring.go /START1/,/STOP1/
* Executable documentation
* Plans
Deploy executable examples throughout:
- godoc (already done)
- blog
- code walks
- Go By Example
- wiki
.link http://golang.org/pkg/strings/#example_Contains