- removed gratuitous empty lines that creeped into command line output
- changed comment color to a dark green so that links don't visually melt into them
- removed some TODOs
- updated doc.go
R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/8108044
- convert all formatters that require a *token.FileSet to
consistenly use a *PageInfo as first argument instead
- adjust templates correspondingly
- fix outstanding bug from previous CL 8005044
Going forward, with this change the affected functions have
access to the full page "context" (PageInfo), not just the
respective file set. This will permit better context-dependent
formatting in the future.
R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/7860049
The gofmt function was returning a string, which isn't the right type.
Three cheers for dynamic typing.
R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/7917044
- A note doesn't have to be in the first
comment of a comment group anymore, and
several notes may appear in the same comment
group (e.g., it is fairly common to have a
TODO(uid) note immediately following another
comment).
- Define a doc.Note type which also contains
note uid and position info.
- Better formatting in godoc output. The position
information is not yet used, but could be used to
locate the note in the source text if desired.
Fixes#4843.
R=r, cnicolaou
CC=gobot, golang-dev
https://golang.org/cl/7496048
Fixed package.txt and adjusted package.html to match
structure (swapped if branches).
Fixes#4861.
R=golang-dev, adg, rsc
CC=golang-dev
https://golang.org/cl/7714043
pkg/go/doc: move BUG notes from Package.Bugs to the general Package.Notes field.
Removing .Bugs would break existing code so it's left in for now.
R=gri, gri, gary.burd, dsymonds, rsc, kevlar
CC=golang-dev
https://golang.org/cl/7341053
Added the command line flag -ex to godoc to print examples in
text output.
Samples from the generated output:
$ godoc -ex strings Index
...
func Index(s, sep string) int
Index returns the index of the first instance of sep in s, or -1 if sep
is not present in s.
Example:
fmt.Println(strings.Index("chicken", "ken"))
fmt.Println(strings.Index("chicken", "dmr"))
// Output:
// 4
// -1
...
$ godoc -ex container/heap
...
package heap
import "container/heap"
Package heap provides heap operations for any type that implements
heap.Interface. A heap is a tree with the property that each node is the
minimum-valued node in its subtree.
Example:
// This example demonstrates an integer heap built using the heap interface.
package heap_test
import (
"container/heap"
"fmt"
...
Example:
// This example demonstrates a priority queue built using the heap interface.
package heap_test
import (
"container/heap"
"fmt"
)
...
Fixes#3587.
R=golang-dev, minux.ma, adg, rsc, gri
CC=golang-dev
https://golang.org/cl/7356043
Also:
- faster code for example extraction
- simplify handling of command documentation:
all "main" packages are treated as commands
- various minor cleanups along the way
For commands written in Go, any doc.go file containing
documentation must now be part of package main (rather
then package documentation), otherwise the documentation
won't show up in godoc (it will still build, though).
For commands written in C, documentation may still be
in doc.go files defining package documentation, but the
recommended way is to explicitly ignore those files with
a +build ignore constraint to define package main.
Fixes#4806.
R=adg, rsc, dave, bradfitz
CC=golang-dev
https://golang.org/cl/7333046
If Python blocks in the SSL handshake it seems to be
completely uninterruptible, and I've been seeing it
block for at least hours recently. I don't know if the
problem is on the client side or the server side or
somewhere in the network, but setting the timeout
at least means you're guaranteed a new shell prompt
(after printing some errors).
R=golang-dev, bradfitz, minux.ma
CC=golang-dev
https://golang.org/cl/7337048
Add support for displaying the notes of the form 'MARKER(userid): comment' now collected by the go/doc package. Any two or more uppercase letters are recognised as a marker.
R=gri, rsc, bradfitz
CC=golang-dev
https://golang.org/cl/7334044
Putting it before the Index (where it is now) is wrong:
we don't even know what's in the package yet.
Fixes#4484.
R=adg, dsymonds
CC=golang-dev
https://golang.org/cl/6868071
The new version of rietveld pushed 1.5 hours ago
requires HTTPS now, otherwise it issues a 301
to HTTPS which we barfed on.
R=golang-dev
CC=golang-dev
https://golang.org/cl/6782135
In recent Python versions .reason is a read-only property that simply gives you the msg value.
Fixes#4024
R=golang-dev, adg
CC=golang-dev
https://golang.org/cl/6545052
For golang.org I intend to rewrite the jquery link in godoc.html
to point to the Google-hosted jquery.js.
R=dsymonds, minux.ma
CC=golang-dev
https://golang.org/cl/6589071
The decorator hides the number of function arguments from Mercurial,
so Mercurial cannot give proper error messages about commands
invoked with the wrong number of arguments.
Left a 'dummy' hgcommand decorator in place as a way to document
what functions are hg commands, and just in case we need some other
kind of hack in the future.
R=adg, rsc
CC=golang-dev
https://golang.org/cl/6488059
Some browsers (e.g. IE9) ignore the case of 'id' attributes
which can lead to conflicts. Prefix non-generated 'id's with
"pkg-" to make them different from any generated attribute.
Also: Added missing entry for "Other packages" to top-level
index.
Fixes#3851.
R=adg, dsymonds
CC=golang-dev
https://golang.org/cl/6449105
We explicitly use plainformatter to avoid the
user's debug setting changing our behavior.
Fixes#3603.
R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/6201069
Docstrings were not being set for the wrapper
functions returned by the hgcommand decorator.
R=golang-dev, minux.ma, rsc
CC=golang-dev
https://golang.org/cl/6059043
In a browser with many open tabs, the tab titles become short
and uninformative because they all start with the same prefix
("Package ", "Directory ", etc.).
Permit use of shorter tab titles that start with the relevant
information first.
Fixes#3365.
R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5865056
srcLink includes the / now; adding another yields //,
which means something else entirely in URLs.
Fixes#3327.
R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5823060
We use the absence of a Title to detect the front page.
I can't find other pages without titles, so this seems reasonable.
R=golang-dev, bradfitz, gri
CC=golang-dev
https://golang.org/cl/5797076
Mercurial: the Python of version control systems.
Python: the Mercurial of programming languages.
R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5777066
If I click on links which should send you to source code (e.g. type, function, etc),
the link is to //src/... (instead of /src/...).
This causes a DNS resolution failure on the browser.
Quick fix is to remove the leading / from package.html
(since godoc.go src links automatically add a leading / as necessary).
Fixes#3193.
R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/5730059
The motivation for this CL is to support $GOPATH well.
Since we already have a FileSystem interface, implement a
Plan 9-style name space. Bind each of the $GOPATH src
directories onto the $GOROOT src/pkg directory: now
everything is laid out exactly like a normal $GOROOT and
needs very little special case code.
The filter files are no longer used (by us), so I think they
can just be deleted. Similarly, the Mapping code and the
FileSystem interface were two different ways to accomplish
the same end, so delete the Mapping code.
Within the implementation, since FileSystem is defined to be
slash-separated, use package path consistently, leaving
path/filepath only for manipulating operating system paths.
I kept the -path flag, but I think it can be deleted too.
Fixes#2234.
Fixes#3046.
R=gri, r, r, rsc
CC=golang-dev
https://golang.org/cl/5711058
The main change is simple: Both the Directory and DirEntry
struct have an extra field 'HasPkg' indicating whether the
directory contains any package files. The remaining changes
are more comments and adjustments to the template files.
Fixes#3121.
R=golang-dev, bradfitz, sameer
CC=golang-dev
https://golang.org/cl/5699072
This is not the finished product,
but a good checkpoint from which to
proceed with further development.
R=golang-dev, dsymonds, r
CC=golang-dev
https://golang.org/cl/5571061
If this happens, something is misconfigured.
If we don't test for this explicitly, MatchAt ends
up calling itself recursively forever.
R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5576066
Compare:
http://swtch.com/junk/regexp0.html [old]
http://swtch.com/junk/regexp.html [new]
Especially for packages with large APIs, this makes the
overview more promiment, so that it can give the appropriate
context for reading the API list. This should help significantly
in packages with large APIs, like net, so that the first thing users
see is not a jumble of functions but an introduction to the package.
R=adg, gri, r, kevlar, dsymonds, rogpeppe
CC=golang-dev
https://golang.org/cl/5573068
Separating Method from Func made the code only more complicated
without adding much to the useability/readability of the API.
Reverted to where it was, but leaving the new method-specific
fields Orig and Level.
Former clients (godoc) of doc.Method only used the Func fields;
and because Func was embedded, no changes are needed with respect
to the removal of Method.
Changed type of Func.Recv from ast.Expr to string. This was a
long-standing TODO. Also implemented Func.Orig field (another TODO).
No further go/doc API changes are expected for Go 1.
R=rsc, r, r
CC=golang-dev
https://golang.org/cl/5577043
Also, disable server-side generation of TOC for commands as they would
only ever show Overview. The JS does a better job (for now).
Fixes#2732.
R=gri, dsymonds
CC=golang-dev
https://golang.org/cl/5558046
- the main changes are removing the Doc suffix
from the exported types, so instead of
doc.TypeDoc one will have doc.Type, etc.
- All exported types now have a Name (or Names) field.
For Values, the Names field lists all declared variables
or constants.
- Methods have additional information about where they are
coming from.
- There's a mode field instead of a bool to
control the package's operation, which makes
it easier to extend w/o API changes.
Except for the partially implemented new Method type,
this is based on existing code. A clean rewrite is in
progress based on this new API.
R=rsc, kevlar
CC=golang-dev
https://golang.org/cl/5528060
Example:
PACKAGE
package utf8
import "unicode/utf8"
Package utf8 implements functions and constants to support text
encoded in UTF-8. This package calls a Unicode character a rune for
brevity.
CONSTANTS
const (
RuneError = unicode.ReplacementChar // the "error" Rune or "replacement character".
RuneSelf = 0x80 // characters below Runeself are represented as themselves in a single byte.
UTFMax = 4 // maximum number of bytes of a UTF-8 encoded Unicode character.
)
Numbers fundamental to the encoding.
FUNCTIONS
func DecodeLastRune(p []byte) (r rune, size int)
DecodeLastRune unpacks the last UTF-8 encoding in p and returns the
rune and its width in bytes.
func DecodeLastRuneInString(s string) (r rune, size int)
DecodeLastRuneInString is like DecodeLastRune but its input is a
string.
func DecodeRune(p []byte) (r rune, size int)
DecodeRune unpacks the first UTF-8 encoding in p and returns the rune
and its width in bytes.
func DecodeRuneInString(s string) (r rune, size int)
DecodeRuneInString is like DecodeRune but its input is a string.
func EncodeRune(p []byte, r rune) int
EncodeRune writes into p (which must be large enough) the UTF-8
encoding of the rune. It returns the number of bytes written.
func FullRune(p []byte) bool
FullRune reports whether the bytes in p begin with a full UTF-8
encoding of a rune. An invalid encoding is considered a full Rune
since it will convert as a width-1 error rune.
func FullRuneInString(s string) bool
FullRuneInString is like FullRune but its input is a string.
func RuneCount(p []byte) int
RuneCount returns the number of runes in p. Erroneous and short
encodings are treated as single runes of width 1 byte.
func RuneCountInString(s string) (n int)
RuneCountInString is like RuneCount but its input is a string.
func RuneLen(r rune) int
RuneLen returns the number of bytes required to encode the rune.
func RuneStart(b byte) bool
RuneStart reports whether the byte could be the first byte of an
encoded rune. Second and subsequent bytes always have the top two
bits set to 10.
func Valid(p []byte) bool
Valid reports whether p consists entirely of valid UTF-8-encoded
runes.
func ValidString(s string) bool
ValidString reports whether s consists entirely of valid UTF-8-encoded
runes.
TYPES
type String struct {
// contains filtered or unexported fields
}
String wraps a regular string with a small structure that provides
more efficient indexing by code point index, as opposed to byte index.
Scanning incrementally forwards or backwards is O(1) per index
operation (although not as fast a range clause going forwards).
Random access is O(N) in the length of the string, but the overhead is
less than always scanning from the beginning. If the string is ASCII,
random access is O(1). Unlike the built-in string type, String has
internal mutable state and is not thread-safe.
func NewString(contents string) *String
NewString returns a new UTF-8 string with the provided contents.
func (s *String) At(i int) rune
At returns the rune with index i in the String. The sequence of runes
is the same as iterating over the contents with a "for range" clause.
func (s *String) Init(contents string) *String
Init initializes an existing String to hold the provided contents.
It returns a pointer to the initialized String.
func (s *String) IsASCII() bool
IsASCII returns a boolean indicating whether the String contains only
ASCII bytes.
func (s *String) RuneCount() int
RuneCount returns the number of runes (Unicode code points) in the
String.
func (s *String) Slice(i, j int) string
Slice returns the string sliced at rune positions [i:j].
func (s *String) String() string
String returns the contents of the String. This method also means the
String is directly printable by fmt.Print.
Fixes#2479.
R=golang-dev, dsymonds, mattn.jp, r, gri, r
CC=golang-dev
https://golang.org/cl/5472051
