--- /dev/null
+<!--{
+ "Title": "Static analysis features of godoc"
+}-->
+
+<style>
+ span.err { 'font-size:120%; color:darkred; background-color: yellow; }
+ img.ss { margin-left: 1in; } /* screenshot */
+ img.dotted { border: thin dotted; }
+</style>
+
+<!-- Images were grabbed from Chrome/Linux at 150% zoom, and are
+ displayed at 66% of natural size. This allows users to zoom a
+ little before seeing pixels. -->
+
+<p>
+ When invoked with the <code>-analysis</code> flag, godoc performs
+ static analysis on the Go packages it indexes and displays the
+ results in the source and package views. This document provides a
+ brief tour of these features.
+</p>
+
+<h2>Type analysis features</h2>
+<p>
+ <code>godoc -analysis=type</code> performs static checking similar
+ to that done by a compiler: it detects ill-formed programs, resolves
+ each identifier to the entity it denotes, computes the type of each
+ expression and the method set of each type, and determines which
+ types are assignable to each interface type.
+
+ <b>Type analysis</b> is relatively quick, requiring about 10 seconds for
+ the >200 packages of the standard library, for example.
+</p>
+
+<h3>Compiler errors</h3>
+<p>
+ If any source file contains a compilation error, the source view
+ will highlight the errant location in red. Hovering over it
+ displays the error message.
+</p>
+<img class="ss" width='811' src='error1.png'><br/>
+
+<h3>Identifier resolution</h3>
+<p>
+ In the source view, every referring identifier is annotated with
+ information about the language entity it refers to: a package,
+ constant, variable, type, function or statement label.
+
+ Hovering over the identifier reveals the entity's kind and type
+ (e.g. <code>var x int</code> or <code>func f
+ func(int) string</code>).
+</p>
+<img class="ss" width='652' src='ident-field.png'><br/>
+<br/>
+<img class="ss" width='652' src='ident-func.png'>
+<p>
+ Clicking the link takes you to the entity's definition.
+</p>
+<img class="ss" width='652' src='ident-def.png'><br/>
+
+<h3>Type information: size/alignment, method set, interfaces</h3>
+<p>
+ Clicking on the identifier that defines a named type causes a panel
+ to appear, displaying information about the named type, including
+ its size and alignment in bytes, its
+ <a href='http://golang.org/ref/spec#Method_sets'>method set</a>, and its
+ <i>implements</i> relation: the set of types T that are assignable to
+ or from this type U where at least one of T or U is an interface.
+
+ This example shows information about <code>net/rpc.methodType</code>.
+</p>
+<img class="ss" width='470' src='typeinfo-src.png'>
+<p>
+ The method set includes not only the declared methods of the type,
+ but also any methods "promoted" from anonymous fields of structs,
+ such as <code>sync.Mutex</code> in this example.
+
+ In addition, the receiver type is displayed as <code>*T</code> or
+ <code>T</code> depending on whether it requires the address or just
+ a copy of the receiver value.
+</p>
+<p>
+ The method set and <i>implements</i> relation are also available
+ via the package view.
+</p>
+<img class="ss dotted" width='716' src='typeinfo-pkg.png'>
+
+<h2>Pointer analysis features</h2>
+<p>
+ <code>godoc -analysis=pointer</code> additionally performs a precise
+ whole-program <b>pointer analysis</b>. In other words, it
+ approximates the set of memory locations to which each
+ reference—not just vars of kind <code>*T</code>, but also
+ <code>[]T</code>, <code>func</code>, <code>map</code>,
+ <code>chan</code>, and <code>interface</code>—may refer. This
+ information reveals the possible destinations of each dynamic call
+ (via a <code>func</code> variable or interface method), and the
+ relationship between send and receive operations on the same
+ channel.
+</p>
+<p>
+ Compared to type analysis, pointer analysis requires more time and
+ memory, and is impractical for code bases exceeding a million lines.
+</p>
+
+<h3>Call graph navigation</h3>
+<p>
+ When pointer analysis is complete, the source view annotates the
+ code with <b>callers</b> and <b>callees</b> information: callers
+ information is associated with the <code>func</code> keyword that
+ declares a function, and callees information is associated with the
+ open paren '<span style="color: dark-blue"><code>(</code></span>' of
+ a function call.
+</p>
+<p>
+ In this example, hovering over the declaration of the
+ <code>rot13</code> function (defined in strings/strings_test.go)
+ reveals that it is called in exactly one place.
+</p>
+<img class="ss" width='612' src='callers1.png'>
+<p>
+ Clicking the link navigates to the sole caller. (If there were
+ multiple callers, a list of choices would be displayed first.)
+</p>
+<img class="ss" width='680' src='callers2.png'>
+<p>
+ Notice that hovering over this call reveals that there are 19
+ possible callees at this site, of which our <code>rot13</code>
+ function was just one: this is a dynamic call through a variable of
+ type <code>func(rune) rune</code>.
+
+ Clicking on the call brings up the list of all 19 potential callees,
+ shown truncated. Many of them are anonymous functions.
+</p>
+<img class="ss" width='564' src='call3.png'>
+<p>
+ Pointer analysis gives a very precise approximation of the call
+ graph compared to type-based techniques.
+
+ As a case in point, the next example shows the dynamic call inside
+ the <code>testing</code> package responsible for calling all
+ user-defined functions named <code>Example<i>XYZ</i></code>.
+</p>
+<img class="ss" width='361' src='call-eg.png'>
+<p>
+ Recall that all such functions have type <code>func()</code>,
+ i.e. no arguments and no results. A type-based approximation could
+ only conclude that this call might dispatch to any function matching
+ that type—and these are very numerous in most
+ programs—but pointer analysis can track the flow of specific
+ <code>func</code> values through the testing package.
+
+ As an indication of its precision, the result contains only
+ functions whose name starts with <code>Example</code>.
+</p>
+
+<h3>Intra-package call graph</h3>
+<p>
+ The same call graph information is presented in a very different way
+ in the package view. For each package, an interactive tree view
+ allows exploration of the call graph as it relates to just that
+ package; all functions from other packages are elided.
+
+ The roots of the tree are the external entry points of the package:
+ not only its exported functions, but also any unexported or
+ anonymous functions that are called (dynamically) from outside the
+ package.
+</p>
+<p>
+ This example shows the entry points of the
+ <code>path/filepath</code> package, with the call graph for
+ <code>Glob</code> expanded several levels
+</p>
+<img class="ss dotted" width='501' src='ipcg-pkg.png'>
+<p>
+ Notice that the nodes for Glob and Join appear multiple times: the
+ tree is a partial unrolling of a cyclic graph; the full unrolling
+ is in general infinite.
+</p>
+<p>
+ For each function documented in the package view, another
+ interactive tree view allows exploration of the same graph starting
+ at that function.
+
+ This is a portion of the internal graph of
+ <code>net/http.ListenAndServe</code>.
+</p>
+<img class="ss dotted" width='455' src='ipcg-func.png'>
+
+<h3>Channel peers (send ↔ receive)</h3>
+<p>
+ Because concurrent Go programs use channels to pass not just values
+ but also control between different goroutines, it is natural when
+ reading Go code to want to navigate from a channel send to the
+ corresponding receive so as to understand the sequence of events.
+</p>
+<p>
+ Godoc annotates every channel operation—make, send, range,
+ receive, close—with a link to a panel displaying information
+ about other operations that might alias the same channel.
+</p>
+<p>
+ This example, from the tests of <code>net/http</code>, shows a send
+ operation on a <code>chan bool</code>.
+</p>
+<img class="ss" width='811' src='chan1.png'>
+<p>
+ Clicking on the <code><-</code> send operator reveals that this
+ channel is made at a unique location (line 332) and that there are
+ three receive operations that might read this value.
+
+ It hardly needs pointing out that some channel element types are
+ very widely used (e.g. struct{}, bool, int, interface{}) and that a
+ typical Go program might contain dozens of receive operations on a
+ value of type <code>chan bool</code>; yet the pointer analysis is
+ able to distinguish operations on channels at a much finer precision
+ than based on their type alone.
+</p>
+<p>
+ Notice also that the send occurs in a different (anonymous) function
+ from the outer one containing the <code>make</code> and the receive
+ operations.
+</p>
+<p>
+ Here's another example of send on a different <code>chan
+ bool</code>, also in package <code>net/http</code>:
+</p>
+<img class="ss" width='774' src='chan2a.png'>
+<p>
+ The analysis finds just one receive operation that might receive
+ from this channel, in the test for this feature.
+</p>
+<img class="ss" width='737' src='chan2b.png'>
+
+<h2>Known issues</h2>
+<p>
+ All analysis results pertain to exactly
+ one configuration (e.g. amd64 linux). Files that are conditionally
+ compiled based on different platforms or build tags are not visible
+ to the analysis.
+</p>
+<p>
+ Files that <code>import "C"</code> require
+ preprocessing by the cgo tool. The file offsets after preprocessing
+ do not align with the unpreprocessed file, so markup is misaligned.
+</p>
+<p>
+ Files are not periodically re-analyzed.
+ If the files change underneath the running server, the displayed
+ markup is misaligned.
+</p>
+<p>
+ Additional issues are listed at
+ <a href='https://go.googlesource.com/tools/+/master/godoc/analysis/README'>tools/godoc/analysis/README</a>.
+</p>
projects / dotfiles / .git / blobdiff