Go docs

Golang-Syd, Oct 17, 2012

Rob Pike

Google, Inc.

Documentation

2

Text

There are many ways to show documentation as text

3

Man pages: Unix 1st Edition, 1971

4

Man pages: Apple OS X 10.8, 2012

5

Javadoc 1996+

6

Javadoc 1996+

7

Godoc 2009+

8

Godoc 2009+

9

Godoc

go.dev/pkg/utf16

10

blog.golang.org

11

Code walks

12

Community contributions

13

Go wiki

go.dev/wiki

14

Gopkgdoc

go.pkgdoc.org

15

Gopkgdoc

go.pkgdoc.org/code.google.com/p/goauth2/oauth

16

Go By Example

gobyexample.com

17

Go By Example

gobyexample.com/timeouts

18

Talks

19

Presentations

We give a lot of talks.

Most of the tools for presentations focus on style, not ease of creation.

20

Present

In the go.talks repo, have a new tool: present. 

go get code.google.com/p/go.talks/present

Took about an hour to put this talk together.

Docs:

go.pkgdoc.org/code.google.com/p/go.talks/present

21

Input for the previous slide

* 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
22

Input for the previous slide redux

* Input for the previous slide

.code go-docs.slide /^\* Present$/,/^\.link/
23

Revenge of the input for the previous slide

* Input for the previous slide redux

.code go-docs.slide /^\*.*previous/,/^\.code/
24

Many choices

Lots of presentations, different styles.

25

Fatal flaw

They all have code.

Can't execute the code!

Want to edit and play.

26

The playground

27

Can run code from the browser

go.dev/play

28

The tour

29

Can run code from the browser

go.dev/tour

30

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.

31

Go Concurrency Patterns

An extract from the talk.

32

Multiplexing

These programs make Joe and Ann count in lockstep.
We can instead use a fan-in function to let whosoever is ready talk. 

func fanIn(input1, input2 <-chan string) <-chan string {
    c := make(chan string)
    go func() { for { c <- <-input1 } }()
    go func() { for { c <- <-input2 } }()
    return c
}

// +build ignore,OMIT

package main

import (
	"fmt"
	"math/rand"
	"time"
)


func main() {
    c := fanIn(boring("Joe"), boring("Ann"))
    for i := 0; i < 10; i++ {
        fmt.Println(<-c)
    }
    fmt.Println("You're both boring; I'm leaving.")
}


// 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
33

.code and .play

Input for the previous slide: 

* 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/
34

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
35

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
36

.code and .play again

The input for the Multiplexing slide again: 

* 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/
37

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. 

func fanIn(input1, input2 <-chan string) <-chan string {
    c := make(chan string)
    go func() { for { c <- <-input1 } }()
    go func() { for { c <- <-input2 } }()
    return c
}

// +build ignore,OMIT

package main

import (
	"fmt"
	"math/rand"
	"time"
)


func main() {
    c := fanIn(boring("Joe"), boring("Ann"))
    for i := 0; i < 10; i++ {
        fmt.Println(<-c)
    }
    fmt.Println("You're both boring; I'm leaving.")
}


// 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
38

Executable documentation

39

Plans

Deploy executable examples throughout:

go.dev/pkg/strings/#example_Contains

40

Thank you

Rob Pike

Google, Inc.

https://go.dev

Use the left and right arrow keys or click the left and right edges of the page to navigate between slides.
(Press 'H' or navigate to hide this message.)