Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

encoding/hex: Suggestions for doc improvements #11254

Closed
ianlancetaylor opened this issue Jun 17, 2015 · 6 comments
Closed

encoding/hex: Suggestions for doc improvements #11254

ianlancetaylor opened this issue Jun 17, 2015 · 6 comments

Comments

@ianlancetaylor
Copy link
Contributor

Quoting from https://groups.google.com/d/msg/golang-nuts/eV3uNlEFPrc/KeHIjyN2oVEJ (not all of this is appropriate in my opinion, but it is useful information from a Go newbie):

Now, let's look at a specific package, e.g. https://golang.org/pkg/encoding/hex/

Already, we can see there are no examples here, making it tough for a newcomer to follow along with. For example, it's not clear that the functions that are listed here need to be prefixed with the "hex." prefix. Yes, that's a simple language thing, but if it's not re-enforced in the documentation with a few examples, it takes that much longer to learn.

Consider this (BAD/CONFUSING):
var ErrLength = errors.New("encoding/hex: odd length hex string")

What is that? My first assumption is that this is some type of package variable because it's under the "Variables" heading. It's only by comparing this to other packages that I can guess that this is a reference to a particular error message. But without an example to see how it might arise, I have no idea what to do with this info or what exactly it pertains to.

BETTER: include an example of working with the returned variables to see how/why they might be relevant or omit this entirely and just list the message strings.

BAD: func Dumper

This "crosses the beams" by referencing another package: "io". Without an example to work off of, it's not clear how one might instantiate an io.Writer or what might be done with an io.WriteCloser. We end up banging our heads on a different wall over at the "io" docs.

BETTER: include an example here so we aren't on a wild goose chase to figure out how to instantiate io.Writer objects.

BAD: func DecodeString

Again, no example, so immediately I have to pay the toll of fiddling with this to see how it works. Perhaps an example like this:

bytes, _ := hex.DecodeString("AE")
fmt.Println(hex.EncodeToString(bytes)) // ae (lowercase)

It might be worth mentioning that the output is always lowercase, and it would be good to explain the behavior that pops up if your input is out of range, e.g. "XX". This is why it would be useful to describe the parameters and output in their own dedicated sections.

BAD: func Decode

The explanation includes "Decode decodes src into DecodedLen(len(src)) bytes" -- nesting like that is more concise, but it's harder to follow. I'm not entirely sure I understand what this function does. Again, an example would help clarify this more than paragraphs of text.

BETTER: ???

@dr2chase
Copy link
Contributor

It occurred to me that perhaps we could prefix examples with (for example) "// Example:" and that godoc might be able to use that as a useful cue -- perhaps examples are not expanded inline, for brevity, but a link is automatically provided.

And happily (?) that string is relatively rare in the Go sources:

git grep -i -e "// *Example:" .
cmd/vet/types.go:               // Example:
database/sql/sql.go:// Example:
html/template/error.go:// Example:
html/template/error.go: // Example:
html/template/error.go: // Example:
html/template/error.go: // Example:
html/template/error.go: // Example:
html/template/error.go: // Example:
html/template/error.go: // Example:
html/template/error.go: // Example:
reflect/all_test.go:// Example:
regexp/regexp.go:// Example:

and ("// For example:")

git grep -i -e "// *for *Example:" .
cmd/compile/internal/gc/esc.go:// For example:
cmd/internal/rsc.io/x86/x86asm/decode.go:                       // for example:
crypto/x509/pem_decrypt.go:     // For example:
database/sql/sql.go:// For example: an INSERT and UPDATE.
encoding/asn1/common.go:// For example: a BIT STRING is tagged [UNIVERSAL 3] by default (although ASN.1
runtime/stubs.go:// For example:
testing/quick/quick.go:// For example:
unicode/letter.go:// For example:

@griesemer
Copy link
Contributor

@dr2chase We already have an ExampleX mechanism in the test package. What we do lack are examples, rather than more machinery.

@ianlancetaylor
Copy link
Contributor Author

@dr2chase We do already support examples--are you suggesting a different kind of example?

@dr2chase
Copy link
Contributor

I think that is what I want, or nearly so, but I didn't know about it.

There's a tradeoff between the convenience of inline editing and the rigor
of tested executable code, I think what we have now looks good. Perhaps if
we solicited user feedback, it could be along the lines of a button for "I
vote for an example here".

I think I should add example-writing to my list of things it would be good
to do in my copious free time. It would help me learn go and the libraries.

On Wed, Jun 17, 2015 at 3:39 PM, Ian Lance Taylor notifications@github.com
wrote:

@dr2chase https://github.com/dr2chase We do already support
examples--are you suggesting a different kind of example?


Reply to this email directly or view it on GitHub
#11254 (comment).

@gopherbot
Copy link

CL https://golang.org/cl/26697 mentions this issue.

@gopherbot
Copy link

CL https://golang.org/cl/28482 mentions this issue.

@golang golang locked and limited conversation to collaborators Sep 8, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants