[amatsukawa]

I don't really know Go except for like 5 min of reading up on its syntax, so I could be wrong, but this assertion that it was not obvious how to write to a file in the documentation surprised me. So I clicked on the stackoverflow link.

OpenFile returns type File from the signature. http://golang.org/pkg/os/#OpenFile

Scanning through the methods (or doing a cmd + f search for "disk") has this method http://golang.org/pkg/os/#File.Sync

Method description says "Sync commits the current contents of the file to stable storage. Typically, this means flushing the file system's in-memory copy of recently written data to disk." Isn't that what you want?

Was it as clear as the C# example? Probably not. But I don't think this was terribly hard to find. Code examples will come in time, as the language matures.

IMO whether to put code examples into the documentation is really a choice by the language maintainers. Lots of code examples can also clutter the docs. I prefer to just have the docs tell me what each function does. If I really get confused, I can google for examples. Java also doesn't really have code examples right in the documentation, but they aren't hard to find because it's been around for a long time. For example, Googling for "java code example how to append to a file" and click on the first link.

[thirsteh]

Okay, it might not be totally obvious, but File implements io.Reader and io.Writer (you can tell by the Read and Write methods.) Therefore, you can use all the functions that take an io.Reader or io.Writer, i.e. all the functions in http://golang.org/pkg/io/ and http://golang.org/pkg/io/ioutil/. It also implements io.Closer (Close() method), which you can use to flush and close the file when you're done.

It would probably be helpful if there was some kind of auto-generated list of the known (or at least stdlib) interfaces a given type implements, even if you don't actively declare it (like Java 'implements'.)