Documentation and Example of GetReadme #323
Conversation
While using `go-github`, I found using the RepositoryContent functions challenging to parse without a multiple detailed reads of the GitHub API. The primary challenge came from the results of GetReadme, which returns text in base64. To address it, I've added comments on this, and similar functions that return base64, suggesting that the user uses `Decode()`. `String()` was also commented since it does not result in a Readme in string format, which had me confused for a good hour or so.
This commit provides a simple how-to to parse an existing README.md file using the GetReadme command available through RepositoriesServices. It includes the different error handling I use, which have each come in handy.
github/repos_contents.go
Outdated
| } | ||
|
|
||
| // GetReadme gets the Readme file for the repository. | ||
| // GetReadme gets the Readme file for the repository, which is stored as base64. |
There was a problem hiding this comment.
Rather than all these various doc changes, would it not be sufficient to just document the Content field of RepositoryContent to say that it may be encoded, and if so, then use Decode to decode it?
I don't really want to document that Readme is always stored as base64 because I don't actually know that that's true. Otherwise, why would GitHub bother returning an "encoding" value?
There was a problem hiding this comment.
Great point - I'll address this.
There was a problem hiding this comment.
I'm thinking what could be said safely is that it's retrieving encoded content. For instance: // GetReadme gets the encoded readme file for the repository.
Or was part of the point is you don't want to assume that it will remain encoded?
There was a problem hiding this comment.
As I type it up, I think it's great to have a note on RepositoryContent, though I want to give people a heads up as they look at each command. I could go either way, but I err on sharing wherever it hurt as a user.
There was a problem hiding this comment.
These methods clearly return a RepositoryContent struct, so wouldn't it be reasonable to expect a user to look at that type to then know what to do with it?
Nowhere else in go-github (that I can recall), does a method document how to use the returned type. Instead, the type itself documents what its fields are, special cases about when they may or may not be present, etc. I think the one exception may be where we mention that the caller is responsible for closing an io.ReadCloser similar to how the net/http documents that, but I may be misremembering that.
I added the language that highlights content returned as *mostlikely* (but not for sure) needing to be `.Decode()`-ed. This newly minted lesson-learned is captured as an example of collecting and reading the readme for this repository. May it prevent others from having similar I-dont-get-it moments like I did!
This example was added to the repos_contents_test.go file as ExampleRepositoriesService_GetReadme(). RIP
|
I think we're on track now @willnorris. The edits we landed on are mostly in 02f6480. The only addition is a description for |
Decode only works if r.Content is actually encoded, which I'm not sure that it always will be. GetContent will return the content, decoding it only if necessary. Deprecate the old Decode method. Related to google#323
Decode only works if r.Content is actually encoded, which I'm not sure that it always will be. GetContent will return the content, decoding it only if necessary. Deprecate the old Decode method. Also expand and cleanup the tests for both of these methods. Related to google#323
Decode only works if r.Content is actually encoded, which I'm not sure that it always will be. GetContent will return the content, decoding it only if necessary. Deprecate the old Decode method. Also expand and cleanup the tests for both of these methods. Related to google#323
Decode only works if r.Content is actually encoded, which I'm not sure that it always will be. GetContent will return the content, decoding it only if necessary. Deprecate the old Decode method. Also expand and cleanup the tests for both of these methods. Related to #323
|
With the new |
2 participants
I had a tough time figuring out how to view a readme through go-github. Adding a couple more notes on documentation for godoc to pick up and I added an example of doing so.
Fixes #322