HELP! Is it me or are godocs hard to read?

agolangf · · 68 次点击    
<p>I come from Python and most libraries are really WELL documented, and even beginners could understand what functions do.</p> <p>Is there a trick or a standard in reading the docs? or are the docs im reading just real bad?</p> <p>(golos-go)</p> <hr/>**评论:**<br/><br/>deusmetallum: <pre><p>I find the standard library docs really easy to read, but if you&#39;re reading something which isn&#39;t part of that library, I&#39;m not surprised if you&#39;re having issues. Documentation is 100% human written.</p></pre>mcouturier: <pre><p>I would like to see more examples. Seeing a bunch of abstractions sometimes leave you confused.</p></pre>natefinch: <pre><p>I find most Go projects are better documented than other languages I&#39;ve used. The fact that Go has a lot of tooling that encourages you to write documentation helps, I think. However, docs are still generally written by humans, so the total quality can vary significantly.</p> <p>Do you have some specific projects you&#39;re having trouble understanding? There may be some pointers we can give.</p> <p>One thing I find can be confusing at first is that standalone functions that return a type, are grouped under that type in godoc.</p></pre>3Dayo: <pre><p>Coming from Python, I too found godocs hard to read in my early days of go. Thing is godoc != docs.python.org. Godocs is more of an api reference. 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. </p> <p>But 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. And that, IMO is the main difference between the two.</p></pre>Simerty: <pre><p>I actually thought Python&#39;s documentation was absolutely awful, <a href="http://cryto.net/%7Ejoepie91/blog/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/" rel="nofollow">and so do others</a>.</p> <p>As an example, look at <a href="https://docs.python.org/2/library/os.html#os.statvfs" rel="nofollow">statvfs</a>. 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&#39;t make it absolutely clear what is happening.</p> <p>Compare that to <a href="https://golang.org/pkg/os/#File.Stat" rel="nofollow">Golang&#39;s os.Stat</a>. Even without reading the description I can see what the types of the returned value as well as the arguments passed in. The types alone give me a good idea of what the function&#39;s purpose is. The description explicitly states the purpose, and I can click on any of the types to see their exact layout and what they contain. </p> <p>I would argue that even a non-programmer could look at os.Stat in the godocs and understand what is happening. At the same time, established programmers might look at python&#39;s os.statvfs and still not understand exactly what it is doing.</p></pre>trevorbramble: <pre><p>That library&#39;s docs look pretty typical, and yes I too usually find them hard to read.</p> <p>In my opinion the generated documentation rarely does a good job of describing their context. There are pervasive (and sometimes large) assumptions that you are reading that documentation with an existing grasp of what the package&#39;s purpose and jargon are. I think people just assume the generated package API docs are enough, and there&#39;s little/no need for human-to-human language to be added. It can be very frustrating.</p></pre>slrz: <pre><blockquote> <p>There are pervasive (and sometimes large) assumptions that you are reading that documentation with an existing grasp of what the package&#39;s purpose and jargon are.</p> </blockquote> <p>But aren&#39;t those assumptions correct most of the time? If I have no clue what HTTP is, why would I want to use an HTTP library? If I want to learn about HTTP, a specific implementation&#39;s API reference is probably not the most suitable place to start at.</p></pre>sh41: <pre><p>Can you point to some examples of what you consider real bad? Then we can discuss it with more context.</p> <p>I think Go&#39;s standard library documentation is excellent. I really enjoy how explicit, clear, and succinct it is on average. It says everything that&#39;s important, nothing that isn&#39;t.</p> <p>I use <a href="https://godoc.org" rel="nofollow">godoc.org</a> to read it most of the time, it has a helpful F keyboard shortcut to jump to any identifier quickly. What do you use?</p></pre>icholy: <pre><p>After using it for a while, I like godoc a LOT more than python&#39;s docs. It grows on you.</p></pre>deranjer: <pre><p>Came here to say the same thing. I thought python had decent docs usually but I&#39;ve found that overall I like godoc more.</p></pre>mwholt: <pre><p>The godoc is technical, it&#39;s not a tutorial format like many of the Python docs. It takes a little getting used to, but its conciseness and correctness (most of the time) is really helpful.</p></pre>Kraigius: <pre><p>Of course, it&#39;s all a matter of opinion but I always found the python doc awful. The index isn&#39;t that good and it&#39;s really difficult to find the thing you want since there&#39;s pile and pile of text and complex examples of things I don&#39;t care about with shit tons of terminal dump.</p> <p>For example, let&#39;s say I&#39;m looking on how to make optional arguments with argparse: <a href="https://imgur.com/a/vZQzV" rel="nofollow">https://imgur.com/a/vZQzV</a> utterly useless. So many results because they are just dumping the terminal and it always contain the &#34;optional arguments&#34; text.</p> <p>Godoc is a technical doc while docs.python seems more like a giant brick of a book.</p></pre>imguralbumbot: <pre><p><sup>Hi, I&#39;m a bot for linking direct images of albums with only 1 image</sup></p> <p><a href="https://i.imgur.com/XxrCw1T.png" rel="nofollow">https://i.imgur.com/XxrCw1T.png</a></p> <p><sup><sup><a href="https://github.com/AUTplayed/imguralbumbot" rel="nofollow">Source</a></sup></sup> <sup><sup>|</sup></sup> <sup><sup><a href="https://github.com/AUTplayed/imguralbumbot/blob/master/README.md" rel="nofollow">Why?</a></sup></sup> <sup><sup>|</sup></sup> <sup><sup><a href="https://np.reddit.com/user/AUTplayed/" rel="nofollow">Creator</a></sup></sup> <sup><sup>|</sup></sup> <sup><sup><a href="https://np.reddit.com/message/compose/?to=imguralbumbot&amp;subject=ignoreme&amp;message=ignoreme" rel="nofollow">ignoreme</a></sup></sup> <sup><sup>|</sup></sup> <sup><sup><a href="https://np.reddit.com/message/compose/?to=imguralbumbot&amp;subject=delet%20this&amp;message=delet%20this%20dmy16ne" rel="nofollow">deletthis</a></sup></sup> </p></pre>ligustah: <pre><p>I found that almost all libraries from <a href="https://github.com/avelino/awesome-go" rel="nofollow">the awesome go list</a> included really good documentation. I agree, though, that there is also a decent number of libraries that lack documentation in key parts, or are somewhat misleading. In those cases I would usually just click the names in godoc to get to the source code on github, since most of the time the code is really easily readable. This is not to say that I think good source code doesn&#39;t need documentation, but it certainly helps in cases where it&#39;s lacking.</p></pre>AndyNemmity: <pre><p>It&#39;s really hard to read until you do it for awhile, then it gets easier to read than any other language.</p> <p>I felt bad at first, because when I communicated that it was hard to understand, people just repeated back it&#39;s far easier. Now that it&#39;s becoming easier for me, I get their point.</p> <p>Once you get into a flow with it, it is easier. </p></pre>Simerty: <pre><p>I see people saying the godocs are hard to read, but I don&#39;t really understand why. </p> <p>I&#39;m not saying they aren&#39;t hard to read, but was curious to know what made them hard for you to read early on, and what could have been done to make the documentation better.</p></pre>shovelpost: <pre><p>Go docs can provide runnable examples which are very hard to beat when it comes to understanding an unknown package. Can you provide some links of the docs you are reading? Maybe they are just inadequate.</p></pre>Zikes: <pre><p>The godoc docs tend to be dry, but well-organized, consistent, and complete (as far as code coverage goes). Most often the element I need most that&#39;s missing is examples. It&#39;s easy to look at any one piece and see what it does, but without idiomatic examples it can be really hard to figure out how all the pieces are intended to fit together. When I find the godocs are lacking in examples I&#39;ll first look for a README, then <code>_test.go</code> files.</p></pre>justinisrael: <pre><p>But isn&#39;t that just a fault of the author and not a limitation of godoc? Godocs support examples. </p></pre>Zikes: <pre><p>Definitely, but it&#39;s less of a guarantee and most often the missing element, because it is optional.</p></pre>SeerUD: <pre><p>I find godoc to be good for API documentation, and maybe showing some basic examples, etc. but for <em>guides</em>, like cookbooks and that sort of thing, you&#39;re not going to find a replacement to making something a bit more custom.</p> <p>There are some libraries that have both godocs for API documentation and some more complete documentation elsewhere. In some cases you might not need to do that though. Some people may think godoc is the one true documentation tool, and never leave it though unfortunately, and as a result some things aren&#39;t very well documented sometimes.</p></pre>justinisrael: <pre><p>A lot of people have agreed that godoc is great for easily providing an API reference. I agree as well. But I wonder if it would make godoc even more useful to offer extended directives and roles like what Sphinx offers. What if godoc had better support for referencing, sections linking, and other formatting options so that you could generate more useful &#34;guides&#34; in addition to the API style docs?</p></pre>joetsai: <pre><p><a href="https://github.com/golang/go/issues/18342#issuecomment-267683549" rel="nofollow">Python docs are manually curated separately</a> from the source-code, while Go docs are auto-generated from the source-code. Manually-curated docs will always be superior to auto-generated docs, but carry the obvious disadvantage of additional work for the library developer.</p> <p>For auto-generated docs, Go docs are pretty good. However, I still have my gripes. My main gripe is the inability to have a user-defined sections to group consts/vars/types/functions together that are semantically related.</p> <p>I proposed supporting godoc sections: <a href="https://github.com/golang/go/issues/18342" rel="nofollow">https://github.com/golang/go/issues/18342</a></p> <p>I haven&#39;t gotten around to working on a prototype, but my mock of what certain packages would look like with it shows that it improves readability of docs.</p></pre>tv64738: <pre><blockquote> <p>Manually-curated docs will always be superior to auto-generated docs</p> </blockquote> <p>Not true for the case where they no longer match the actual source.</p></pre>ProgressCheck: <pre><p>You get more accustomed to it.</p></pre>kalekold: <pre><p>I find them hard to read because of the terrible typesetting. I usually just read the source code.</p></pre>caymanbruce: <pre><p>Godocs is way better than Apple&#39;s Objective-C Docs in iOS. At least I can read the source code and know what libraries that part of code is using. The only thing I find hard to read is the &#34;Effective Go&#34; book on the same site.</p></pre>
68 次点击  
加入收藏 微博
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传