this repo has no description
pkg: fix godoc mistakes across several packages
Fix doc comments that were copied from Go's standard library
without adjusting for CUE's function names, parameter names,
and return types.
Along the way, we also fix a few typos and other human errors.
Changes in pkg/regexp:
- Find: "returns a list" to "returns a string", "in b" to "in s"
- FindAllNamedSubmatch: typo "the named used" to "the names used"
- FindNamedSubmatch: example output showed a list, but it returns a map
- FindSubmatch: "a list of lists" to "a list", "in b" to "in s"
- ReplaceAll: "empty slice" to "empty string"
Changes in pkg/strings:
- Package doc: remove stuttered "strings.package strings."
- ByteAt: "underlying strings or byte" to "underlying byte slice"
- ByteSlice: "underlying string data" to "underlying byte slice"
- MinRunes: "except all strings" to "accept all strings"
- MaxRunes: same "except" to "accept" typo, plus add missing period
Changes in pkg/list:
- IsSortedStrings: "a sorted lists" to "a sorted list"
Changes in pkg/html:
- Escape: "UnescapeString" to "Unescape"
- Unescape: "EscapeString" to "Escape"
Changes in pkg/net:
- ParseIP: "returns nil" to "returns an error"
Changes in pkg/encoding/hex:
- Decode: parameter name "src" to "s"
Signed-off-by: Daniel Martí <mvdan@mvdan.cc>
Change-Id: I6d00d4e0ea475bd64ae5cd358b33269a14dffd03
Reviewed-on: https://cue.gerrithub.io/c/cue-lang/cue/+/1233353
Reviewed-by: Matthew Sackman <matthew@cue.works>
Unity-Result: CUE porcuepine <cue.porcuepine@gmail.com>
TryBot-Result: CUEcueckoo <cueckoo@cuelang.org>
+20
-20
+2
-2
pkg/encoding/hex/hex.go
+2
-2
pkg/encoding/hex/hex.go
···
36
36
37
37
// Decode returns the bytes represented by the hexadecimal string s.
38
38
//
39
-
// Decode expects that src contains only hexadecimal
40
-
// characters and that src has even length.
39
+
// Decode expects that s contains only hexadecimal
40
+
// characters and that s has even length.
41
41
// If the input is malformed, Decode returns
42
42
// the bytes decoded before the error.
43
43
func Decode(s string) ([]byte, error) {
+3
-3
pkg/html/html.go
+3
-3
pkg/html/html.go
···
24
24
25
25
// Escape escapes special characters like "<" to become "<". It
26
26
// escapes only five such characters: <, >, &, ' and ".
27
-
// UnescapeString(Escape(s)) == s always holds, but the converse isn't
27
+
// Unescape(Escape(s)) == s always holds, but the converse isn't
28
28
// always true.
29
29
func Escape(s string) string {
30
30
return html.EscapeString(s)
31
31
}
32
32
33
33
// Unescape unescapes entities like "<" to become "<". It unescapes a
34
-
// larger range of entities than EscapeString escapes. For example, "á"
34
+
// larger range of entities than Escape escapes. For example, "á"
35
35
// unescapes to "á", as does "á" and "á".
36
-
// Unescape(EscapeString(s)) == s always holds, but the converse isn't
36
+
// Unescape(Escape(s)) == s always holds, but the converse isn't
37
37
// always true.
38
38
func Unescape(s string) string {
39
39
return html.UnescapeString(s)
+1
-1
pkg/list/sort.go
+1
-1
pkg/list/sort.go
+1
-1
pkg/net/ip.go
+1
-1
pkg/net/ip.go
···
116
116
// The string s can be in dotted decimal ("192.0.2.1")
117
117
// or IPv6 ("2001:db8::68") form.
118
118
// If s is not a valid textual representation of an IP address,
119
-
// ParseIP returns nil.
119
+
// ParseIP returns an error.
120
120
func ParseIP(s string) ([]uint, error) {
121
121
goip, err := netip.ParseAddr(s)
122
122
if err != nil {
+6
-6
pkg/regexp/manual.go
+6
-6
pkg/regexp/manual.go
···
62
62
63
63
var errNoMatch = errors.New("no match")
64
64
65
-
// Find returns a list holding the text of the leftmost match in b of the regular expression.
65
+
// Find returns a string holding the text of the leftmost match in s of the regular expression.
66
66
// A return value of bottom indicates no match.
67
67
func Find(pattern, s string) (string, error) {
68
68
re, err := regexp.Compile(pattern)
···
93
93
}
94
94
95
95
// FindAllNamedSubmatch is like [FindAllSubmatch], but returns a list of maps
96
-
// with the named used in capturing groups. See [FindNamedSubmatch] for an
96
+
// with the names used in capturing groups. See [FindNamedSubmatch] for an
97
97
// example on how to use named groups.
98
98
func FindAllNamedSubmatch(pattern, s string, n int) ([]map[string]string, error) {
99
99
re, err := regexp.Compile(pattern)
···
148
148
//
149
149
// Output:
150
150
//
151
-
// [{person: "World"}]
151
+
// {person: "World"}
152
152
func FindNamedSubmatch(pattern, s string) (map[string]string, error) {
153
153
re, err := regexp.Compile(pattern)
154
154
if err != nil {
···
171
171
return r, nil
172
172
}
173
173
174
-
// FindSubmatch returns a list of lists holding the text of the leftmost
175
-
// match of the regular expression in b and the matches, if any, of its
174
+
// FindSubmatch returns a list holding the text of the leftmost
175
+
// match of the regular expression in s and the matches, if any, of its
176
176
// subexpressions, as defined by the 'Submatch' descriptions in the package
177
177
// comment.
178
178
// A return value of bottom indicates no match.
···
197
197
// corresponding index; other names refer to capturing parentheses named with
198
198
// the (?P<name>...) syntax. A reference to an out of range or unmatched index
199
199
// or a name that is not present in the regular expression is replaced with an
200
-
// empty slice.
200
+
// empty string.
201
201
//
202
202
// In the $name form, name is taken to be as long as possible: $1x is
203
203
// equivalent to ${1x}, not ${1}x, and, $10 is equivalent to ${10}, not ${1}0.
+7
-7
pkg/strings/manual.go
+7
-7
pkg/strings/manual.go
···
13
13
// limitations under the License.
14
14
15
15
// Package strings implements simple functions to manipulate UTF-8 encoded
16
-
// strings.package strings.
16
+
// strings.
17
17
//
18
18
// Some of the functions in this package are specifically intended as field
19
19
// constraints. For instance, MaxRunes as used in this CUE program
···
32
32
"unicode/utf8"
33
33
)
34
34
35
-
// ByteAt reports the ith byte of the underlying strings or byte.
35
+
// ByteAt reports the ith byte of the underlying byte slice.
36
36
func ByteAt(b []byte, i int) (byte, error) {
37
37
if i < 0 || i >= len(b) {
38
38
return 0, fmt.Errorf("index out of range")
···
40
40
return b[i], nil
41
41
}
42
42
43
-
// ByteSlice reports the bytes of the underlying string data from the start
43
+
// ByteSlice reports the bytes of the underlying byte slice from the start
44
44
// index up to but not including the end index.
45
45
func ByteSlice(b []byte, start, end int) ([]byte, error) {
46
46
if start < 0 || start > end || end > len(b) {
···
55
55
}
56
56
57
57
// MinRunes reports whether the number of runes (Unicode codepoints) in a string
58
-
// is at least a certain minimum. MinRunes can be used a field constraint to
59
-
// except all strings for which this property holds.
58
+
// is at least a certain minimum. MinRunes can be used as a field constraint to
59
+
// accept all strings for which this property holds.
60
60
func MinRunes(s string, min int) bool {
61
61
// TODO: CUE strings cannot be invalid UTF-8. In case this changes, we need
62
62
// to use the following conversion to count properly:
···
65
65
}
66
66
67
67
// MaxRunes reports whether the number of runes (Unicode codepoints) in a string
68
-
// exceeds a certain maximum. MaxRunes can be used a field constraint to
69
-
// except all strings for which this property holds
68
+
// exceeds a certain maximum. MaxRunes can be used as a field constraint to
69
+
// accept all strings for which this property holds.
70
70
func MaxRunes(s string, max int) bool {
71
71
// See comment in MinRunes implementation.
72
72
return utf8.RuneCountInString(s) <= max