V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
Morriaty
V2EX  ›  程序员

Golang 社区规模应该不算小了,为什么大部分第三方包的文档还是很简陋?

  •  
  •   Morriaty · 2017-10-16 16:19:30 +08:00 · 4169 次点击
    这是一个创建于 2356 天前的主题,其中的信息可能已经有所发展或是发生改变。

    GoDoc 里绝大部分包的文档都只是 API 列表,而没有使用 demo,或者quick start.

    现在引用第三方包,就只能在源代码里跳来跳去,很难受啊,手动捂脸

    15 条回复    2017-10-17 10:05:38 +08:00
    yangtukun1412
        1
    yangtukun1412  
       2017-10-16 16:25:31 +08:00   ❤️ 1
    因为 godoc, 导致很多人喜欢写注释自动生成文档...最多再加几个 example.
    per
        2
    per  
       2017-10-16 16:27:48 +08:00
    赞同一楼的说法.毕竟我就是这样做的.😓
    legendlzy
        3
    legendlzy  
       2017-10-16 17:01:11 +08:00
    赞同 1 楼。。所以要找个方法简直难受
    zts1993
        4
    zts1993  
       2017-10-16 17:06:33 +08:00
    golang 第三方库质量不敢恭维,能自己写的建议自己造轮子。
    lizon
        5
    lizon  
       2017-10-16 17:09:18 +08:00
    golang 的嵌套层次远没有其他语言那么多,看源码没有其他语言那么痛苦,几个核心结构看一下差不多就了解个大概

    如果一个第三方包写得又复杂,doc 又简陋,那就换个更好的,或者给它写黑盒测试,或者自己写轮子,或者忍着

    这头像,要不是搜了图,差点认成我老婆
    okletswin
        6
    okletswin  
       2017-10-16 17:29:01 +08:00
    @lizon
    哎码,猝不及防地装了一 B
    gowk
        7
    gowk  
       2017-10-16 17:41:08 +08:00
    源代码即文档
    Morriaty
        8
    Morriaty  
    OP
       2017-10-16 17:42:07 +08:00
    @yangtukun1412
    @per

    文档并不一定要 Owner 去写啊,我是说目前的 Go 的新生军力量不小了,为什么就没有群策群力去维护文档?

    感觉还是社区习惯的问题,像 python,哪怕一个 100 stars 的库,基本都会有详尽的 quick start.
    mason961125
        9
    mason961125  
       2017-10-16 18:33:20 +08:00
    @Morriaty 其实就是一楼说的,有 GoDoc 那么方便的平台,都不想再进一步的写了。不过一些 import 较多的库也都有很多的 examples 了,看看也能用。
    scofieldpeng
        10
    scofieldpeng  
       2017-10-16 20:03:07 +08:00
    有了 godoc 还需要啥文档,包开头简单说明下,扔一个小的例子,完事儿,看不懂?直接看源码呗,基本好一个质量不差的包每个 api 那儿都会有简单的说明,ps:golang 的官方包源码看起来也很爽
    reus
        11
    reus  
       2017-10-16 22:16:59 +08:00
    godoc 够了,还不够就去看 *_test.go ,没有测试代码的就不要用
    janxin
        12
    janxin  
       2017-10-17 08:52:16 +08:00 via iPhone
    测试代码就是使用 demo,文档稍微写一下用法,我确实就是这样的,这样不需要写太多文档。

    不过也确实对新入门不是特别友好,不过习惯了也没什么不一样。
    kuro1
        13
    kuro1  
       2017-10-17 09:15:42 +08:00
    因为有 godoc,自然就懒惰了...确实不太友好
    JamesRuan
        14
    JamesRuan  
       2017-10-17 09:45:05 +08:00
    自认为文档还是很完善的: https://github.com/jamesruan/sodium

    文档不完善其实就是习惯不好没写呗:)
    mengzhuo
        15
    mengzhuo  
       2017-10-17 10:05:38 +08:00 via iPhone
    楼上各位,Godoc 也可以加 example 的
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2780 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 12:31 · PVG 20:31 · LAX 05:31 · JFK 08:31
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.