This CL introduces the go.Example type and go.Examples functions that
are used to represent and extract code samples from Go source.
They should be of the form:
// Output of this function.
func ExampleFoo() {
fmt.Println("Output of this function.")
}
It also modifies godoc to read example code from _test.go files,
and include them in the HTML output with JavaScript-driven toggles.
It also implements testing of example functions with gotest.
The stdout/stderr is compared against the output comment on the
function.
This CL includes examples for the sort.Ints function and the
sort.SortInts type. After patching this CL in and re-building go/doc
and godoc, try
godoc -http=localhost:6060
and visit http://localhost:6060/pkg/sort/
R=gri, r, rsc
CC=golang-dev
https://golang.org/cl/5137041
Use naming convention for template variables
to indicate "escaped-ness" for easier reviewing.
(per suggestion from bradfitz)
R=bradfitz
CC=golang-dev
https://golang.org/cl/4914041
Since the posLink_url also adds a non-URL attribute, the quoting and URL-escaping
must happen inside posLink_url (otherwise the non-URL attribute becomes part or the
URL portion of the tag.
R=r
CC=golang-dev
https://golang.org/cl/4888041
- rename template funcs for better consistency and
sort them into groups of related functionality
- try to be more consistent with html vs url escaping
R=r
CC=golang-dev
https://golang.org/cl/4887041
- simplified pipelines
- simplified templates by using template variables
- converted most old-style formatters into new-style funcs
- fixed some escaping bugs (use of url escaping where it was missing)
R=r, dsymonds
CC=golang-dev
https://golang.org/cl/4868044
- first step; rough conversion of all template files
- there is plenty of opportunity for cleanups/simplifications (next CLs)
- html and text output as before
R=r, dsymonds
CC=golang-dev
https://golang.org/cl/4852048
Neither gofmt nor godoc are making use of a Styler (for
token-specific formatting) anymore. Stylers interacted in complicated
ways with HTML-escaping which was why the printer needed an HTML mode
in the first place.
godoc now uses a more powerful and general text formatting
function that does HTML escaping, text selection, and can
handle token-specific formatting if so desired (currently
used only for comments).
As a consequence, cleaned up uses of go/printer in godoc;
simplified the various write utility functions, and also
removed the need for the "html" template format (in favor of
html-esc which now does the same and is used more pervasively).
Applied gofmt -w src misc to verify no changes occured,
and tested godoc manually.
There should be no visible changes except that (type) code
snippets presented for godoc package documentation now
uses the same formatting as for general source code and
thus comments get the comment-specific color here as well
(not the case at the moment).
(TODO: godoc needs a good automatic test suite).
R=rsc
CC=golang-dev
https://golang.org/cl/4152042
Specifically:
* lib/godoc:
- provide file set (FSet) argument to formatters where needed
* src/cmd:
- cgo, ebnflint, godoc, gofmt, goinstall: provide file set (fset) where needed
- godoc: remove local binary search with sort.Search (change by rsc),
extract file set for formatters
* src/pkg:
- exp/eval: remove embedded token.Position fields from nodes and replace
with named token.Pos fields; add corresponding Pos() accessor methods
- go/token: added file.Line(), changed signature of File.Position()
* test/fixedbugs/:
- bug206.go: change test to not rely on token.Pos details
* added various extra comments
* Runs all.bash
* gofmt formats all of src, misc w/o changes
* godoc runs
* performance:
- The new version of godoc consumes about the same space after indexing
has completed, but indexing is half the speed. Significant space savings
are expected from smaller ASTs, but since they are thrown away after a
file has been indexed, this is not visible anymore. The slower indexing
time is due to the much more expensive computation of line information.
However, with the new compressed position information, indexing can be
rewritten and simplified. Furthermore, computing the line info can be
done more efficiently.
New godoc, immediately after indexing completed (best of three runs):
PID COMMAND %CPU TIME #TH #PRTS #MREGS RPRVT RSHRD RSIZE VSIZE
44381 godoc 0.0% 0:38.00 4 19 149 145M 184K 148M 176M
2010/12/03 17:58:35 index updated (39.231s, 18505 unique words, 386387 spots)
2010/12/03 17:58:35 bytes=90858456 footprint=199182584
2010/12/03 17:58:36 bytes=47858568 footprint=167295224
Old godoc, immediately after indexing completed (best of three runs):
PID COMMAND %CPU TIME #TH #PRTS #MREGS RPRVT RSHRD RSIZE VSIZE
23167 godoc 0.0% 0:22.02 4 17 132 129M 184K 132M 173M
2010/12/03 14:51:32 index updated (24.892s, 18765 unique words, 393830 spots)
2010/12/03 14:51:32 bytes=66404528 footprint=163907832
2010/12/03 14:51:32 bytes=46282224 footprint=163907832
The different numbers for unique words/spots stem from the fact the the
two workspaces are not exactly identical. The new godoc maintains a large
file set data structure during indexing which (probably) is the reason
for the larger heap (90858456 vs 66404528) before garbage collection.
R=rsc, r
CC=golang-dev
https://golang.org/cl/3050041
- change the various url-xxx formatters to return a relative URL path
- make the leading '/' for URLs explicit in the template
- on the way change some |html formatters to |html-esc
(html should only be used for formatting AST nodes)
R=rsc, r
CC=golang-dev
https://golang.org/cl/740041
- on the commandline: godoc -x big
- in a webpage: provide form parameter ?m=src
Known issues:
- Positioning of comments incorrect in several cases. Separate CL.
- Need a link/menu to switch between different modes of presentation
in the web view.
R=rsc
CC=golang-dev
https://golang.org/cl/376041
Example use: godoc -path=/home/user1:/home/build/foo -http=:6666
will start a local godoc that maps urls starting with /pkg/user1 or
/pkg/foo to the respective roots specified in the path.
Missing: Handling of overlapping package directories, multiple
packages per directory.
R=rsc
CC=golang-dev
https://golang.org/cl/206078
(this was surprisingly hard to get right in HTML)
- show modification times in source directory listings
- various tweaks
R=rsc
http://go/go-review/1024024
- replaced deprecated use of </font> with </span> tag
- added html escaping to godoc formatters where missing
- enabled text format for package documentation
R=rsc
http://go/go-review/1017001
- the first HTML comment in those files is extracted as page
title when serving them
- lib/godoc.html is top-level template for all pages served
- experimented a bit with package documentation layout
(feedback welcome)
- various related cleanups
TODO:
- The / page (doc/root.html) content repeats links that are
in the navigation bar. It needs to be cleaned up.
R=rsc
DELTA=826 (86 added, 692 deleted, 48 changed)
OCL=35230
CL=35245
- emit line tag id's in html mode
- support for general html tags
- better names for a few identifiers
godoc.go:
- emit links from exported names to source code
(actual placement needs fine-tuning)
R=rsc
DELTA=108 (68 added, 4 deleted, 36 changed)
OCL=32639
CL=32654
- more orthogonal functionality of filter functions for better re-use
go/doc/doc.go:
- simplified interface
- collect filenames of packages so that they can be shown
godoc:
- removed TODO, show list of package (linked) files used to create documentation
R=rsc
DELTA=130 (68 added, 24 deleted, 38 changed)
OCL=32549
CL=32552
ast.go:
- rename Comments -> CommentGroup (less confusion)
- change all comments/docs to be *CommentGroup
filter.go:
- do not remove unassociated comments from program as part
of export filtering (they are needed by doc.go for BUG comments)
scanner.go:
- exclude '\n' from //-style comments
parser.go:
- rewrote collection of comments: now all collected comments
are *ast.CommentGroups
- clarified distinction between leading and trailing comments
- fixed a bug in comment collection (parseGenDecl);
corresponding test case is in printer/testdata
- extra documentation
doc.go:
- collect BUG comments
- corresponding fix for parser bug in comment collection
comment.go:
- simplified regex
printer.go:
- adjust comment printing to new representation
printer_test.go, testdata/*:
- enable printing of doc comments
- extended tests
package.html, package.txt:
- added Bugs section
gofmt:
- enable printing of doc comments
R=rsc
DELTA=339 (126 added, 38 deleted, 175 changed)
OCL=31403
CL=31416
