I think people just assume the generated package API docs are enough, and there's little/no need for human-to-human language to be added. There are pervasive (and sometimes large) assumptions that you are reading that documentation with an existing grasp of what the package's purpose and jargon are. In my opinion the generated documentation rarely does a good job of describing their context. At the same time, established programmers might look at python's os.statvfs and still not understand exactly what it is evorbramble: That library's docs look pretty typical, and yes I too usually find them hard to read.
I would argue that even a non-programmer could look at os.Stat in the godocs and understand what is happening. The description explicitly states the purpose, and I can click on any of the types to see their exact layout and what they contain. The types alone give me a good idea of what the function's purpose is. Even without reading the description I can see what the types of the returned value as well as the arguments passed in. Without prior knowledge how is anyone supposed to know what this function does? What type of data structure does it return? What type is path? A quick glance tells you nothing and even reading the short description doesn't make it absolutely clear what is happening.Ĭompare that to Golang's os.Stat. And that, IMO is the main difference between the two.Simerty: I actually thought Python's documentation was absolutely awful, and so do others.Īs an example, look at statvfs. īut most of what you will run into is a concise explanation of what a function/method does but not how, when or why you would use it. Can it be fleshed out, certainly ive run into a couple of repos with examples that dont assume you already understand the how and the whys of the library. One thing I find can be confusing at first is that standalone functions that return a type, are grouped under that type in godoc.3Dayo: Coming from Python, I too found godocs hard to read in my early days of go. However, docs are still generally written by humans, so the total quality can vary significantly.ĭo you have some specific projects you're having trouble understanding? There may be some pointers we can give. The fact that Go has a lot of tooling that encourages you to write documentation helps, I think. Seeing a bunch of abstractions sometimes leave you confused.natefinch: I find most Go projects are better documented than other languages I've used. Documentation is 100% human written.mcouturier: I would like to see more examples. **评论：**deusmetallum: I find the standard library docs really easy to read, but if you're reading something which isn't part of that library, I'm not surprised if you're having issues. Is there a trick or a standard in reading the docs? or are the docs im reading just real bad? I come from Python and most libraries are really WELL documented, and even beginners could understand what functions do.
0 kommentar(er)
