github.com/graybobo/golang.org-package-offline-cache@v0.0.0-20200626051047-6608995c132f/x/talks/2012/go-docs.slide (about)

     1  Go docs
     2  Golang-Syd, Oct 17, 2012
     3  
     4  Rob Pike
     5  Google, Inc.
     6  @rob_pike
     7  http://golang.org/s/plusrob
     8  http://golang.org
     9  
    10  * Documentation
    11  
    12  * Text
    13  
    14  There are many ways to show documentation as text
    15  
    16  * Man pages: Unix 1st Edition, 1971
    17  
    18  .image go-docs/seek.png
    19  
    20  * Man pages: Apple OS X 10.8, 2012
    21  
    22  .image go-docs/lseek.png
    23  
    24  * Javadoc 1996+
    25  
    26  .image go-docs/javadoc.png
    27  
    28  * Javadoc 1996+
    29  
    30  .image go-docs/javadoc1.png
    31  
    32  * Godoc 2009+
    33  
    34  .image go-docs/godoc.png
    35  
    36  * Godoc 2009+
    37  
    38  .image go-docs/godoc1.png
    39  
    40  * Godoc
    41  
    42  .link http://golang.org/pkg/utf16
    43  
    44  * blog.golang.org
    45  
    46  .image go-docs/blog.png
    47  
    48  * Code walks
    49  
    50  .image go-docs/codewalk.png
    51  
    52  * Community contributions
    53  
    54  * Go wiki
    55  
    56  .link http://golang.org/wiki
    57  
    58  .image go-docs/gowiki.png
    59  
    60  * Gopkgdoc
    61  
    62  .link http://go.pkgdoc.org
    63  
    64  .image go-docs/gopkgdoc.png
    65  
    66  * Gopkgdoc
    67  
    68  .link http://go.pkgdoc.org/code.google.com/p/goauth2/oauth
    69  
    70  * Go By Example
    71  
    72  .link https://gobyexample.com
    73  
    74  .image go-docs/gobyexample.png
    75  
    76  * Go By Example
    77  
    78  .link https://gobyexample.com/timeouts
    79  
    80  * Talks
    81  
    82  * Presentations
    83  
    84  We give a lot of talks.
    85  
    86  Most of the tools for presentations focus on style, not ease of creation.
    87  
    88  * Present
    89  
    90  In the `go.talks` repo, have a new tool: `present`.
    91  
    92  	go get code.google.com/p/go.talks/present
    93  
    94  - Simple
    95  - Easy to use
    96  - Easy, smooth to present
    97  
    98  Took about an hour to put this talk together.
    99  
   100  Docs:
   101  
   102  .link http://go.pkgdoc.org/code.google.com/p/go.talks/present
   103  
   104  * Input for the previous slide
   105  
   106  .code go-docs.slide /^\* Present$/,/^\.link/
   107  
   108  * Input for the previous slide redux
   109  
   110  .code go-docs.slide /^\*.*previous/,/^\.code/
   111  
   112  * Revenge of the input for the the previous slide 
   113  
   114  .code go-docs.slide /^\*.*redux/,/^\.code/
   115  
   116  
   117  * Many choices
   118  
   119  Lots of presentations, different styles.
   120  
   121  * Fatal flaw
   122  
   123  They all have code.
   124  
   125  Can't execute the code!
   126  
   127  Want to edit and play.
   128  
   129  * The playground
   130  
   131  .image go-docs/play.png
   132  
   133  * Can run code from the browser
   134  
   135  .link http://play.golang.org
   136  
   137  * The tour
   138  
   139  .image go-docs/tour.png
   140  
   141  * Can run code from the browser
   142  
   143  .link http://tour.golang.org
   144  
   145  * Use this technology
   146  
   147  Want to embed the playground technology in the other media.
   148  
   149  Triggering example: Go Concurrency Patterns, Google I/O, 2012
   150  
   151  Needed to demonstrate concurrency and the passage of time.
   152  
   153  * Go Concurrency Patterns
   154  
   155  An extract from the talk.
   156  
   157  * Multiplexing
   158  
   159  These programs make Joe and Ann count in lockstep.
   160  We can instead use a fan-in function to let whosoever is ready talk.
   161  
   162  .code go-docs/faninboring.go /START3/,/STOP3/
   163  .play go-docs/faninboring.go /START1/,/STOP1/
   164  
   165  * .code and .play
   166  
   167  Input for the previous slide:
   168  
   169  .code go-docs.slide /^\* Multiplexing/,/^.play/
   170  
   171  * faninboring.go (I)
   172  
   173  	package main
   174  
   175  	import (
   176  		"fmt"
   177  		"math/rand"
   178  		"time"
   179  	)
   180  
   181  	// START1 OMIT
   182  	func main() {
   183  		c := fanIn(boring("Joe"), boring("Ann")) // HL
   184  		for i := 0; i < 10; i++ {
   185  			fmt.Println(<-c) // HL
   186  		}
   187  		fmt.Println("You're both boring; I'm leaving.")
   188  	}
   189  	// STOP1 OMIT
   190  	
   191  * faninboring.go (II)
   192  
   193  	// START2 OMIT
   194  	func boring(msg string) <-chan string { // Returns receive-only channel of strings. // HL
   195  		c := make(chan string)
   196  		go func() { // We launch the goroutine from inside the function. // HL
   197  			for i := 0; ; i++ {
   198  				c <- fmt.Sprintf("%s: %d", msg, i)
   199  				time.Sleep(time.Duration(rand.Intn(2e3)) * time.Millisecond)
   200  			}
   201  		}()
   202  		return c // Return the channel to the caller. // HL
   203  	}
   204  	// STOP2 OMIT
   205  
   206  
   207  	// START3 OMIT
   208  	func fanIn(input1, input2 <-chan string) <-chan string { // HL
   209  		c := make(chan string)
   210  		go func() { for { c <- <-input1 } }() // HL
   211  		go func() { for { c <- <-input2 } }() // HL
   212  		return c
   213  	}
   214  	// STOP3 OMIT
   215  
   216  * .code and .play again
   217  
   218  The input for the Multiplexing slide again:
   219  
   220  .code go-docs.slide /^\* Multiplexing/,/^.play/
   221  
   222  * Multiplexing again
   223  
   224  These programs make Joe and Ann count in lockstep.
   225  We can instead use a fan-in function to let whosoever is ready talk.
   226  
   227  .code go-docs/faninboring.go /START3/,/STOP3/
   228  .play go-docs/faninboring.go /START1/,/STOP1/
   229  
   230  * Executable documentation
   231  
   232  * Plans
   233  
   234  Deploy executable examples throughout:
   235  
   236  - godoc (already done)
   237  - blog
   238  - code walks
   239  - Go By Example
   240  - wiki
   241  
   242  .link http://golang.org/pkg/strings/#example_Contains