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