{"action":"created","issue":{"url":"https://api.github.com/repos/golang/go/issues/11254","labels_url":"https://api.github.com/repos/golang/go/issues/11254/labels{/name}","comments_url":"https://api.github.com/repos/golang/go/issues/11254/comments","events_url":"https://api.github.com/repos/golang/go/issues/11254/events","html_url":"https://github.com/golang/go/issues/11254","id":89035210,"number":11254,"title":"encoding/hex: Suggestions for doc improvements","user":{"login":"ianlancetaylor","id":3194333,"avatar_url":"https://avatars.githubusercontent.com/u/3194333?v=3","gravatar_id":"","url":"https://api.github.com/users/ianlancetaylor","html_url":"https://github.com/ianlancetaylor","followers_url":"https://api.github.com/users/ianlancetaylor/followers","following_url":"https://api.github.com/users/ianlancetaylor/following{/other_user}","gists_url":"https://api.github.com/users/ianlancetaylor/gists{/gist_id}","starred_url":"https://api.github.com/users/ianlancetaylor/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ianlancetaylor/subscriptions","organizations_url":"https://api.github.com/users/ianlancetaylor/orgs","repos_url":"https://api.github.com/users/ianlancetaylor/repos","events_url":"https://api.github.com/users/ianlancetaylor/events{/privacy}","received_events_url":"https://api.github.com/users/ianlancetaylor/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/golang/go/labels/Documentation","name":"Documentation","color":"aaffaa"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/golang/go/milestones/6","html_url":"https://github.com/golang/go/milestones/Unplanned","labels_url":"https://api.github.com/repos/golang/go/milestones/6/labels","id":1055141,"number":6,"title":"Unplanned","description":"No plan to fix in any specific release.\r\n","creator":{"login":"rsc","id":104030,"avatar_url":"https://avatars.githubusercontent.com/u/104030?v=3","gravatar_id":"","url":"https://api.github.com/users/rsc","html_url":"https://github.com/rsc","followers_url":"https://api.github.com/users/rsc/followers","following_url":"https://api.github.com/users/rsc/following{/other_user}","gists_url":"https://api.github.com/users/rsc/gists{/gist_id}","starred_url":"https://api.github.com/users/rsc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rsc/subscriptions","organizations_url":"https://api.github.com/users/rsc/orgs","repos_url":"https://api.github.com/users/rsc/repos","events_url":"https://api.github.com/users/rsc/events{/privacy}","received_events_url":"https://api.github.com/users/rsc/received_events","type":"User","site_admin":false},"open_issues":884,"closed_issues":46,"state":"open","created_at":"2015-04-06T20:47:19Z","updated_at":"2015-06-17T19:00:43Z","due_on":"2099-12-31T05:00:00Z","closed_at":null},"comments":2,"created_at":"2015-06-17T14:36:16Z","updated_at":"2015-06-17T19:38:53Z","closed_at":null,"body":"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):\r\n\r\nNow, let's look at a specific package, e.g. https://golang.org/pkg/encoding/hex/\r\n\r\nAlready, 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.\r\n\r\nConsider this (BAD/CONFUSING):\r\nvar ErrLength = errors.New(\"encoding/hex: odd length hex string\")\r\n\r\nWhat 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.\r\n\r\nBETTER: 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.  \r\n\r\nBAD: func Dumper\r\n\r\nThis \"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.\r\n\r\nBETTER: include an example here so we aren't on a wild goose chase to figure out how to instantiate io.Writer objects.\r\n\r\nBAD: func DecodeString\r\n\r\nAgain, no example, so immediately I have to pay the toll of fiddling with this to see how it works.  Perhaps an example like this:\r\n\r\n    bytes, _ := hex.DecodeString(\"AE\")\r\n    fmt.Println(hex.EncodeToString(bytes)) // ae (lowercase)\r\n\r\n\r\nIt 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.\r\n\r\nBAD: func Decode\r\n\r\nThe 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.\r\n\r\nBETTER: ???"},"comment":{"url":"https://api.github.com/repos/golang/go/issues/comments/112923396","html_url":"https://github.com/golang/go/issues/11254#issuecomment-112923396","issue_url":"https://api.github.com/repos/golang/go/issues/11254","id":112923396,"user":{"login":"griesemer","id":8528975,"avatar_url":"https://avatars.githubusercontent.com/u/8528975?v=3","gravatar_id":"","url":"https://api.github.com/users/griesemer","html_url":"https://github.com/griesemer","followers_url":"https://api.github.com/users/griesemer/followers","following_url":"https://api.github.com/users/griesemer/following{/other_user}","gists_url":"https://api.github.com/users/griesemer/gists{/gist_id}","starred_url":"https://api.github.com/users/griesemer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/griesemer/subscriptions","organizations_url":"https://api.github.com/users/griesemer/orgs","repos_url":"https://api.github.com/users/griesemer/repos","events_url":"https://api.github.com/users/griesemer/events{/privacy}","received_events_url":"https://api.github.com/users/griesemer/received_events","type":"User","site_admin":false},"created_at":"2015-06-17T19:38:53Z","updated_at":"2015-06-17T19:38:53Z","body":"@dr2chase We already have an ExampleX mechanism in the test package. What we do lack are examples, rather than more machinery."}}