Also, the documentation is far better than e.g. that for Java and C#: http://golang.org/pkg/io/ / http://golang.org/pkg/io/ioutil
Reading a file into memory is as simple as:
data, err := ioutil.ReadFile("filename")It covers everything you need to know. The MOST important part being "example". I don't see any on Go's documentation. That just led me to being frustrated. Also, I actually only see a list of functions and a very short, vague description.
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.
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'.)
It was pretty interesting, and I find a few bits were harder to deal with than others (such as {} being required for conditionals, even when on the same line) in terms of my own habits. The language wasn't particularly difficult, but when I got to a few of the higher lessons/challenges, getting the answer took more time than I thought it should, or would with any other language for similar problems.
Searching for go examples is worse than when C# first started out.. searching "golang" yields slightly better results, but still not the easiest thing to search for examples with/on.
There are no examples, the lifeblood of documentation, nor any notes about gotchas?
It's early days in the language so that's not at all bad, but claiming the documentation is better when it's clearly not is odd.
http://msdn.microsoft.com/en-us/library/b9skfh7s.aspx
Also C# and java are going to have tons of examples on SO, so the amount of examples and extra documentation available is incomparable.
Just to be clear, I don't think verbosity means that documentation is better. Documentation is better when it gives you the information you need, and nothing more. That being said, I mostly think Go's documentation is better than Java's, and on par if not slightly better than C#'s. Here's a better example of what I mean, e.g. http://docs.oracle.com/javase/6/docs/api/allclasses-noframe.... vs. http://golang.org/pkg/
Granted, if you have no experience at all with the language--e.g. you haven't even taken the tour at http://tour.golang.org/--the documentation may be hard to read (what does "[]" mean, for example), but that's not the fault of API documentation, which rightly is clear and concise. Rather, that's the job for a comprehensive tutorial, which Go has: http://tour.golang.org/
http://golang.org/pkg/net/#example_Listener
---- begin example ---
package main
---- end example ---