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
Comments
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:
and ("// For example:")
|
@dr2chase We already have an ExampleX mechanism in the test package. What we do lack are examples, rather than more machinery. |
@dr2chase We do already support examples--are you suggesting a different kind of example? |
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 I think I should add example-writing to my list of things it would be good On Wed, Jun 17, 2015 at 3:39 PM, Ian Lance Taylor notifications@github.com
|
CL https://golang.org/cl/26697 mentions this issue. |
CL https://golang.org/cl/28482 mentions this issue. |
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:
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: ???
The text was updated successfully, but these errors were encountered: