aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAgniva De Sarker <agnivade@yahoo.co.in>2018-01-04 11:01:13 +0530
committerAndrew Bonventre <andybons@golang.org>2018-01-08 16:36:02 +0000
commitbd15c8473871452545ef270a25683cf10926362b (patch)
treeb1af20a2004269691d572793b94b323dd109e9d1
parent4280d3c9435a303a94a9d6cba8092e1448ad956e (diff)
content: fix stale links to line numbers
- Changed the links from go1.3 to master. - Removed trailing spaces from several lines. Fixes golang/go#22488 Change-Id: I41748fea956f0329eca0d520134670fa28618657 Reviewed-on: https://go-review.googlesource.com/86095 Reviewed-by: Andrew Bonventre <andybons@golang.org> Reviewed-by: Kevin Burke <kev@inburke.com>
-rw-r--r--content/godoc-documenting-go-code.article2
-rw-r--r--content/playground.article48
2 files changed, 25 insertions, 25 deletions
diff --git a/content/godoc-documenting-go-code.article b/content/godoc-documenting-go-code.article
index 05f5b1d..13df471 100644
--- a/content/godoc-documenting-go-code.article
+++ b/content/godoc-documenting-go-code.article
@@ -10,7 +10,7 @@ The Go project takes documentation seriously. Documentation is a huge part of ma
To that end, we have developed the [[http://golang.org/cmd/godoc/][godoc]] documentation tool. This article describes godoc's approach to documentation, and explains how you can use our conventions and tools to write good documentation for your own projects.
-Godoc parses Go source code - including comments - and produces documentation as HTML or plain text. The end result is documentation tightly coupled with the code it documents. For example, through godoc's web interface you can navigate from a function's [[http://golang.org/pkg/strings/#HasPrefix][documentation]] to its [[http://golang.org/src/pkg/strings/strings.go?#L312][implementation]] with one click.
+Godoc parses Go source code - including comments - and produces documentation as HTML or plain text. The end result is documentation tightly coupled with the code it documents. For example, through godoc's web interface you can navigate from a function's [[http://golang.org/pkg/strings/#HasPrefix][documentation]] to its [[http://golang.org/src/pkg/strings/strings.go#L493][implementation]] with one click.
Godoc is conceptually related to Python's [[http://www.python.org/dev/peps/pep-0257/][Docstring]] and Java's [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html][Javadoc]], but its design is simpler. The comments read by godoc are not language constructs (as with Docstring) nor must they have their own machine-readable syntax (as with Javadoc). Godoc comments are just good comments, the sort you would want to read even if godoc didn't exist.
diff --git a/content/playground.article b/content/playground.article
index 1b3910b..02220b0 100644
--- a/content/playground.article
+++ b/content/playground.article
@@ -18,7 +18,7 @@ from the Go documentation.
You may also have used it by clicking one of the "Run" buttons in a slide
deck on [[https://talks.golang.org/][talks.golang.org]] or a post on this
-very blog
+very blog
(such as the [[https://blog.golang.org/strings][recent article on Strings]]).
In this article we will take a look at how the playground is implemented
@@ -46,7 +46,7 @@ here. The interesting part is how we safely execute arbitrary user code in a
secure environment while still providing core functionality such as time, the
network, and the file system.
-To isolate user programs from Google's infrastructure, the back end runs
+To isolate user programs from Google's infrastructure, the back end runs
them under [[https://developers.google.com/native-client/][Native Client]]
(or "NaCl"), a technology developed by Google to permit the safe execution of
x86 programs inside web browsers. The back end uses a special version of the gc
@@ -55,7 +55,7 @@ tool chain that generates NaCl executables.
(This special tool chain was merged into Go 1.3.
To learn more, read the [[https://golang.org/s/go13nacl][design document]].)
-NaCl limits the amount of CPU and RAM a program may consume, and it prevents
+NaCl limits the amount of CPU and RAM a program may consume, and it prevents
programs from accessing the network or file system.
This presents a problem, however.
Go's concurrency and networking support are among its key strengths,
@@ -101,7 +101,7 @@ To explain the trick we first need to understand how the scheduler manages
sleeping goroutines.
When a goroutine calls `time.Sleep` (or similar) the scheduler adds a timer to
-a heap of pending timers and puts the goroutine to sleep.
+a heap of pending timers and puts the goroutine to sleep.
Meanwhile, a special timer goroutine manages that heap.
When the timer goroutine starts it tells the scheduler to wake
it when the next pending timer is ready to fire and then sleeps.
@@ -182,7 +182,7 @@ To the user it appears that the program is running in real time.
Programs built with the Go's NaCl tool chain cannot access the local machine's
file system. Instead, the `syscall` package's file-related functions
(`Open`, `Read`, `Write`, and so on) operate on an in-memory file system
-that is implemented by the `syscall` package itself.
+that is implemented by the `syscall` package itself.
Since package `syscall` is the interface between the Go code and the operating
system kernel, user programs see the file system exactly the same way as they
would a real one.
@@ -205,17 +205,17 @@ with a set of files that can be used in documentation examples, blog posts, and
the Go Tour.
The implementation can be found in the
-[[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fs_nacl.go][`fs_nacl.go`]] and
-[[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fd_nacl.go][`fd_nacl.go`]] files
+[[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go][`fs_nacl.go`]] and
+[[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go][`fd_nacl.go`]] files
(which, by virtue of their `_nacl` suffix, are built into package `syscall` only
when `GOOS` is set to `nacl`).
-The file system itself is represented by the
-[[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fs_nacl.go#L25][`fsys` struct]],
+The file system itself is represented by the
+[[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L26][`fsys` struct]],
of which a global instance (named `fs`) is created during init time.
The various file-related functions then operate on `fs` instead of making the
actual system call.
-For instance, here is the [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fs_nacl.go#L467][`syscall.Open`]] function:
+For instance, here is the [[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L473][`syscall.Open`]] function:
func Open(path string, openmode int, perm uint32) (fd int, err error) {
fs.mu.Lock()
@@ -228,17 +228,17 @@ For instance, here is the [[https://github.com/golang/go/blob/go1.3/src/pkg/sysc
}
File descriptors are tracked by a global slice named
-[[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fd_nacl.go#L16][`files`]].
-Each file descriptor corresponds to a [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fd_nacl.go#L24][`file`]]
-and each `file` provides a value that implements the [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fd_nacl.go#L29][`fileImpl`]] interface.
+[[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L17][`files`]].
+Each file descriptor corresponds to a [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L23][`file`]]
+and each `file` provides a value that implements the [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L30][`fileImpl`]] interface.
There are several implementations of the interface:
-- regular files and devices (such as `/dev/random`) are represented by [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fs_nacl.go#L57][`fsysFile`]],
-- standard input, output, and error are instances of [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/fd_nacl.go#L215][`naclFile`]], which uses system calls to interact with the actual files (these are a playground program's only way to interact with the outside world),
+- regular files and devices (such as `/dev/random`) are represented by [[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L58][`fsysFile`]],
+- standard input, output, and error are instances of [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L216][`naclFile`]], which uses system calls to interact with the actual files (these are a playground program's only way to interact with the outside world),
- network sockets have their own implementation, discussed in the next section.
-** Faking the network
+** Faking the network
Like the file system, the playground's network stack is an in-process fake
implemented by the `syscall` package. It permits playground projects to use
@@ -256,8 +256,8 @@ implementation of the fake network is larger and more complex than the fake
file system. It must simulate read and write timeouts, different address types
and protocols, and so on.
-The implementation can be found in [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/net_nacl.go][`net_nacl.go`]].
-A good place to start reading is [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/net_nacl.go#L428][`netFile`]], the network socket implementation of the `fileImpl` interface.
+The implementation can be found in [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go][`net_nacl.go`]].
+A good place to start reading is [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go#L461][`netFile`]], the network socket implementation of the `fileImpl` interface.
* The front end
@@ -289,24 +289,24 @@ code for setting up the user interface (the code and output boxes, the run
button, and so on) and communicating with the playground front end.
This implementation is in the file
-[[https://github.com/golang/tools/blob/release-branch.go1.3/godoc/static/playground.js][`playground.js`]]
+[[https://github.com/golang/tools/blob/master/godoc/static/playground.js][`playground.js`]]
in the `go.tools` repository, which can be imported from the
[[https://godoc.org/golang.org/x/tools/godoc/static][`golang.org/x/tools/godoc/static`]] package.
Some of it is clean and some is a bit crufty, as it is the result of
consolidating several divergent implementations of the client code.
-The [[https://github.com/golang/tools/blob/release-branch.go1.3/godoc/static/playground.js#L226][`playground`]]
+The [[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L227][`playground`]]
function takes some HTML elements and turns them into an interactive
playground widget. You should use this function if you want to put the
playground on your own site (see 'Other clients' below).
-The [[https://github.com/golang/tools/blob/release-branch.go1.3/godoc/static/playground.js#L6][`Transport`]]
+The [[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L6][`Transport`]]
interface (not formally defined, this being JavaScript)
abstracts the user interface from the means of talking to the web front end.
-[[https://github.com/golang/tools/blob/release-branch.go1.3/godoc/static/playground.js#L43][`HTTPTransport`]]
+[[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L43][`HTTPTransport`]]
is an implementation of `Transport` that speaks the HTTP-based protocol
-described earlier.
-[[https://github.com/golang/tools/blob/release-branch.go1.3/godoc/static/playground.js#L115][`SocketTransport`]]
+described earlier.
+[[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L115][`SocketTransport`]]
is another implementation that speaks WebSocket (see 'Playing offline' below).
To comply with the [[https://en.wikipedia.org/wiki/Same-origin_policy][same-origin policy]],