Golang项目文档完善

[Iceyer]

主要是dde-daemon和go-lib的文档需要完善。

完善文档的过程也是一个重构代码的过程。今天整理了dde-daemon的蓝牙模块的文档，发现暴露了很多不应该暴露的接口和数据结构，一并做了修复，可以参考下这里：https://cr.deepin.io/#/c/10640 （其实主要是修改大小写 😃 ）。

dde-daemon主要是对外提供DBus接口，只有需要出现在dbus中的struct和方法才需要导出，其他的数据结构都应该作为内部struct。下图是整理前的导出文档和整理后的对比：

对于一些实在需要导出文档，又不会出现在dbus接口中的方法，中午简单讨论了一下，可以放在一个dde-daemon-dev的包，作为一个桌面级别的开发库来构建。

go-lib作为一个标准库，直接按照godoc的规范来实施即可。

[Iceyer]

godoc的一些参考：
http://blog.golang.org/godoc-documenting-go-code
https://godoc.org/github.com/fluhus/godoc-tricks
https://github.com/fluhus/godoc-tricks

[fasheng]

支持适当重构代码，确实有些模块的接口需要调整下了 😀 🙌 👍

不过这里 bluetooth 的 Agent 的接口应该不能隐藏吧，不然无法导出 DBus 接口，也就无法被 bluez 调用...

[Iceyer]

可以导出Dbus的，只要agent的方法是大写的。
这里的agent本来就是实现bluez的Agent接口而已，输入输出都是固定的，没必要暴露。
或者说一开始该Agent暴露的东西都给Bluetooth暴露了。需要对Bluetooth的几个信号和接口做说明。

[fasheng]

明白了
type Agent struct -> type agent struct

[Iceyer]

@jouyouyun @kosl90

[fasheng]

有一个工具叫做 godocdown[1]，可以导出 go doc 为 github markdown 格式，使用方法也很简单

go get github.com/robertkrimen/godocdown/godocdown
cd dde-daemon
godocdown account > developer-center.git/gen/DDE-Daemon-Account.markdown

不过如果考虑到其他项目，如 qt/libdui，好像没有直接导出文档为 markdown 的工具，网上有一种方法是先通过 doxygen 生成 xml，然后再用 pandoc 转换为 markdown（还需要做额外处理？），但不知效果怎样[2]，所以 API 文档的展现方式还有待确定。
[1] https://github.com/robertkrimen/godocdown
[2] http://stackoverflow.com/questions/13081984/generate-documentation-as-markdown-files-using-doxygen

[snyh]

分开做吧．　我们可以先把golang的项目整理出来．　这样先促进代码本身的注释以及结构调整．
之后再和qt方面一起结合实际情况看怎么玩．　　毕竟展现形式都可以很快速的调整．　主要是内容需要持续的花时间以及养成这方面的习惯．

现在麻烦点的事情是决定在哪里放这些online的API文档．　最好能结合CI之类的．　融入到开发中，方便前后端沟通．

[Iceyer]

@fasheng golang的文档就用gowalker.org来展示吧，展示效果比godoc.org好一些。另外也兼容golang.org. gowalker.org支持展示在包根目录下放置的README.md
https://gowalker.org/github.com/linuxdeepin/dde-daemon/
https://gowalker.org/github.com/linuxdeepin/go-lib

[fasheng]

可以，回头我把链接加到 wiki

[snyh]

不过一个索引页面我觉得还是有必要的吧．　

[Iceyer]

要不再docs.deepin.io下放一个索引页面，类似
docs.deepin.io/ref/golang
docs.deepin.io/ref/dtk
原来的docs.deepin.io可以停掉

[snyh]

恩．　不过不知道怎么搭建．
最好是docs.deepin.io/ref/index 里面是所有deepin开发过程中需要的文档
然后docs.deepin.io/ref/{dtk,golang,dde-daemon,gtk,qt} 等就是各种具体的手册

[Iceyer]

golang的可以只放一个索引，这个索引可以人工维护。
C++（dtk，qt等类似的项目）可以用ci和doxygen自动生成html，然后丢上去。doxygen自动生成的文档展示效果还不错。