cryptobyte: minor documentation fix
This change fixes a minor misspelling in the documentation for ReadBytes.
Change-Id: Ia1cfedfce11844c4d901b9aeed52065f3749dfa2
GitHub-Last-Rev: d1560b97807871c356d1b704d4879b1cf94a3fd8
GitHub-Pull-Request: golang/crypto#40
Reviewed-on: https://go-review.googlesource.com/106116
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
diff --git a/cryptobyte/asn1.go b/cryptobyte/asn1.go
index 88ec8b4..bb094a5 100644
--- a/cryptobyte/asn1.go
+++ b/cryptobyte/asn1.go
@@ -224,6 +224,9 @@
// String
+// ReadASN1Boolean decodes an ASN.1 INTEGER and converts it to a boolean
+// representation into out and advances. It reports whether the read
+// was successful.
func (s *String) ReadASN1Boolean(out *bool) bool {
var bytes String
if !s.ReadASN1(&bytes, asn1.INTEGER) || len(bytes) != 1 {
@@ -245,8 +248,8 @@
var bigIntType = reflect.TypeOf((*big.Int)(nil)).Elem()
// ReadASN1Integer decodes an ASN.1 INTEGER into out and advances. If out does
-// not point to an integer or to a big.Int, it panics. It returns true on
-// success and false on error.
+// not point to an integer or to a big.Int, it panics. It reports whether the
+// read was successful.
func (s *String) ReadASN1Integer(out interface{}) bool {
if reflect.TypeOf(out).Kind() != reflect.Ptr {
panic("out is not a pointer")
@@ -359,8 +362,8 @@
return true
}
-// ReadASN1Enum decodes an ASN.1 ENUMERATION into out and advances. It returns
-// true on success and false on error.
+// ReadASN1Enum decodes an ASN.1 ENUMERATION into out and advances. It reports
+// whether the read was successful.
func (s *String) ReadASN1Enum(out *int) bool {
var bytes String
var i int64
@@ -392,7 +395,7 @@
}
// ReadASN1ObjectIdentifier decodes an ASN.1 OBJECT IDENTIFIER into out and
-// advances. It returns true on success and false on error.
+// advances. It reports whether the read was successful.
func (s *String) ReadASN1ObjectIdentifier(out *encoding_asn1.ObjectIdentifier) bool {
var bytes String
if !s.ReadASN1(&bytes, asn1.OBJECT_IDENTIFIER) || len(bytes) == 0 {
@@ -431,7 +434,7 @@
}
// ReadASN1GeneralizedTime decodes an ASN.1 GENERALIZEDTIME into out and
-// advances. It returns true on success and false on error.
+// advances. It reports whether the read was successful.
func (s *String) ReadASN1GeneralizedTime(out *time.Time) bool {
var bytes String
if !s.ReadASN1(&bytes, asn1.GeneralizedTime) {
@@ -449,8 +452,8 @@
return true
}
-// ReadASN1BitString decodes an ASN.1 BIT STRING into out and advances. It
-// returns true on success and false on error.
+// ReadASN1BitString decodes an ASN.1 BIT STRING into out and advances.
+// It reports whether the read was successful.
func (s *String) ReadASN1BitString(out *encoding_asn1.BitString) bool {
var bytes String
if !s.ReadASN1(&bytes, asn1.BIT_STRING) || len(bytes) == 0 {
@@ -471,8 +474,8 @@
}
// ReadASN1BitString decodes an ASN.1 BIT STRING into out and advances. It is
-// an error if the BIT STRING is not a whole number of bytes. This function
-// returns true on success and false on error.
+// an error if the BIT STRING is not a whole number of bytes. It reports
+// whether the read was successful.
func (s *String) ReadASN1BitStringAsBytes(out *[]byte) bool {
var bytes String
if !s.ReadASN1(&bytes, asn1.BIT_STRING) || len(bytes) == 0 {
@@ -489,14 +492,14 @@
// ReadASN1Bytes reads the contents of a DER-encoded ASN.1 element (not including
// tag and length bytes) into out, and advances. The element must match the
-// given tag. It returns true on success and false on error.
+// given tag. It reports whether the read was successful.
func (s *String) ReadASN1Bytes(out *[]byte, tag asn1.Tag) bool {
return s.ReadASN1((*String)(out), tag)
}
// ReadASN1 reads the contents of a DER-encoded ASN.1 element (not including
// tag and length bytes) into out, and advances. The element must match the
-// given tag. It returns true on success and false on error.
+// given tag. It reports whether the read was successful.
//
// Tags greater than 30 are not supported (i.e. low-tag-number format only).
func (s *String) ReadASN1(out *String, tag asn1.Tag) bool {
@@ -509,7 +512,7 @@
// ReadASN1Element reads the contents of a DER-encoded ASN.1 element (including
// tag and length bytes) into out, and advances. The element must match the
-// given tag. It returns true on success and false on error.
+// given tag. It reports whether the read was successful.
//
// Tags greater than 30 are not supported (i.e. low-tag-number format only).
func (s *String) ReadASN1Element(out *String, tag asn1.Tag) bool {
@@ -521,8 +524,8 @@
}
// ReadAnyASN1 reads the contents of a DER-encoded ASN.1 element (not including
-// tag and length bytes) into out, sets outTag to its tag, and advances. It
-// returns true on success and false on error.
+// tag and length bytes) into out, sets outTag to its tag, and advances.
+// It reports whether the read was successful.
//
// Tags greater than 30 are not supported (i.e. low-tag-number format only).
func (s *String) ReadAnyASN1(out *String, outTag *asn1.Tag) bool {
@@ -531,14 +534,14 @@
// ReadAnyASN1Element reads the contents of a DER-encoded ASN.1 element
// (including tag and length bytes) into out, sets outTag to is tag, and
-// advances. It returns true on success and false on error.
+// advances. It reports whether the read was successful.
//
// Tags greater than 30 are not supported (i.e. low-tag-number format only).
func (s *String) ReadAnyASN1Element(out *String, outTag *asn1.Tag) bool {
return s.readASN1(out, outTag, false /* include header */)
}
-// PeekASN1Tag returns true if the next ASN.1 value on the string starts with
+// PeekASN1Tag reports whether the next ASN.1 value on the string starts with
// the given tag.
func (s String) PeekASN1Tag(tag asn1.Tag) bool {
if len(s) == 0 {
@@ -547,7 +550,8 @@
return asn1.Tag(s[0]) == tag
}
-// SkipASN1 reads and discards an ASN.1 element with the given tag.
+// SkipASN1 reads and discards an ASN.1 element with the given tag. It
+// reports whether the operation was successful.
func (s *String) SkipASN1(tag asn1.Tag) bool {
var unused String
return s.ReadASN1(&unused, tag)
@@ -556,7 +560,7 @@
// ReadOptionalASN1 attempts to read the contents of a DER-encoded ASN.1
// element (not including tag and length bytes) tagged with the given tag into
// out. It stores whether an element with the tag was found in outPresent,
-// unless outPresent is nil. It returns true on success and false on error.
+// unless outPresent is nil. It reports whether the read was successful.
func (s *String) ReadOptionalASN1(out *String, outPresent *bool, tag asn1.Tag) bool {
present := s.PeekASN1Tag(tag)
if outPresent != nil {
@@ -569,7 +573,7 @@
}
// SkipOptionalASN1 advances s over an ASN.1 element with the given tag, or
-// else leaves s unchanged.
+// else leaves s unchanged. It reports whether the operation was successful.
func (s *String) SkipOptionalASN1(tag asn1.Tag) bool {
if !s.PeekASN1Tag(tag) {
return true
@@ -581,8 +585,8 @@
// ReadOptionalASN1Integer attempts to read an optional ASN.1 INTEGER
// explicitly tagged with tag into out and advances. If no element with a
// matching tag is present, it writes defaultValue into out instead. If out
-// does not point to an integer or to a big.Int, it panics. It returns true on
-// success and false on error.
+// does not point to an integer or to a big.Int, it panics. It reports
+// whether the read was successful.
func (s *String) ReadOptionalASN1Integer(out interface{}, tag asn1.Tag, defaultValue interface{}) bool {
if reflect.TypeOf(out).Kind() != reflect.Ptr {
panic("out is not a pointer")
@@ -619,8 +623,8 @@
// ReadOptionalASN1OctetString attempts to read an optional ASN.1 OCTET STRING
// explicitly tagged with tag into out and advances. If no element with a
-// matching tag is present, it writes defaultValue into out instead. It returns
-// true on success and false on error.
+// matching tag is present, it writes defaultValue into out instead. It reports
+// whether the read was successful.
func (s *String) ReadOptionalASN1OctetString(out *[]byte, outPresent *bool, tag asn1.Tag) bool {
var present bool
var child String
@@ -644,6 +648,7 @@
// ReadOptionalASN1Boolean sets *out to the value of the next ASN.1 BOOLEAN or,
// if the next bytes are not an ASN.1 BOOLEAN, to the value of defaultValue.
+// It reports whether the operation was successful.
func (s *String) ReadOptionalASN1Boolean(out *bool, defaultValue bool) bool {
var present bool
var child String
diff --git a/cryptobyte/string.go b/cryptobyte/string.go
index 7636fb9..39bf98a 100644
--- a/cryptobyte/string.go
+++ b/cryptobyte/string.go
@@ -37,8 +37,8 @@
return s.read(n) != nil
}
-// ReadUint8 decodes an 8-bit value into out and advances over it. It
-// returns true on success and false on error.
+// ReadUint8 decodes an 8-bit value into out and advances over it.
+// It reports whether the read was successful.
func (s *String) ReadUint8(out *uint8) bool {
v := s.read(1)
if v == nil {
@@ -49,7 +49,7 @@
}
// ReadUint16 decodes a big-endian, 16-bit value into out and advances over it.
-// It returns true on success and false on error.
+// It reports whether the read was successful.
func (s *String) ReadUint16(out *uint16) bool {
v := s.read(2)
if v == nil {
@@ -60,7 +60,7 @@
}
// ReadUint24 decodes a big-endian, 24-bit value into out and advances over it.
-// It returns true on success and false on error.
+// It reports whether the read was successful.
func (s *String) ReadUint24(out *uint32) bool {
v := s.read(3)
if v == nil {
@@ -71,7 +71,7 @@
}
// ReadUint32 decodes a big-endian, 32-bit value into out and advances over it.
-// It returns true on success and false on error.
+// It reports whether the read was successful.
func (s *String) ReadUint32(out *uint32) bool {
v := s.read(4)
if v == nil {
@@ -119,28 +119,27 @@
}
// ReadUint8LengthPrefixed reads the content of an 8-bit length-prefixed value
-// into out and advances over it. It returns true on success and false on
-// error.
+// into out and advances over it. It reports whether the read was successful.
func (s *String) ReadUint8LengthPrefixed(out *String) bool {
return s.readLengthPrefixed(1, out)
}
// ReadUint16LengthPrefixed reads the content of a big-endian, 16-bit
-// length-prefixed value into out and advances over it. It returns true on
-// success and false on error.
+// length-prefixed value into out and advances over it. It reports whether the
+// read was successful.
func (s *String) ReadUint16LengthPrefixed(out *String) bool {
return s.readLengthPrefixed(2, out)
}
// ReadUint24LengthPrefixed reads the content of a big-endian, 24-bit
-// length-prefixed value into out and advances over it. It returns true on
-// success and false on error.
+// length-prefixed value into out and advances over it. It reports whether
+// the read was successful.
func (s *String) ReadUint24LengthPrefixed(out *String) bool {
return s.readLengthPrefixed(3, out)
}
-// ReadBytes reads n bytes into out and advances over them. It returns true on
-// success and false and error.
+// ReadBytes reads n bytes into out and advances over them. It reports
+// whether the read was successful.
func (s *String) ReadBytes(out *[]byte, n int) bool {
v := s.read(n)
if v == nil {
@@ -150,8 +149,8 @@
return true
}
-// CopyBytes copies len(out) bytes into out and advances over them. It returns
-// true on success and false on error.
+// CopyBytes copies len(out) bytes into out and advances over them. It reports
+// whether the copy operation was successful
func (s *String) CopyBytes(out []byte) bool {
n := len(out)
v := s.read(n)
