Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up
for free
Godoc: хороший, плохой, злой
Ilya Kaznacheev
July 18, 2020
Programming
0
13
Godoc: хороший, плохой, злой
Ilya Kaznacheev
July 18, 2020
Tweet
Share
More Decks by Ilya Kaznacheev
See All by Ilya Kaznacheev
dreamworm
0
32
dreamworm
0
33
dreamworm
0
88
dreamworm
0
16
dreamworm
0
47
dreamworm
1
140
dreamworm
0
30
dreamworm
1
28
dreamworm
1
32
Other Decks in Programming
See All in Programming
nori0__
1
490
palkan
2
310
drumato
1
230
manfredsteyer
PRO
0
160
bkuhlmann
2
330
deepu105
0
230
rockname
1
330
techharmony
0
160
timeseriesfr
0
110
tooppoo
1
450
fr0gger
2
2.8k
dora1998
0
170
Featured
See All Featured
sachag
445
36k
kneath
220
15k
chrislema
231
16k
maggiecrowley
10
540
malarkey
119
16k
addyosmani
495
110k
reverentgeek
27
2.1k
geoffreycrofte
25
1k
denniskardys
220
120k
searls
204
37k
edds
56
9.4k
phodgson
88
4k
Transcript
GODOC
Ilya Kaznacheev Remote Backend SWE Основатель Golang Voronezh Соавтор Z-Namespace
podcast Организатор конференций и митапов Любитель кофе
Golang Voronezh - ~30 активных участников - митапы - мероприятия
для новичков
- инструмент для встроенной в код документации - сайт для
хостинга документации публичных проектов godoc
documentation for a code
None
code v1.7.13 docs v1.1.6
documentation as a code
JavaDoc JSDoc Python Docstring ABAPDoc Godoc
what Godoc is?
Formatting guideline // ReadConfig reads configuration file and parses it
depending on tags in structure provided. // Then it reads and parses // // Example: // // type ConfigDatabase struct { // Port string `yaml:"port" env:"PORT" env-default:"5432"` // Host string `yaml:"host" env:"HOST" env-default:"localhost"` // Name string `yaml:"name" env:"NAME" env-default:"postgres"` // User string `yaml:"user" env:"USER" env-default:"user"` // Password string `yaml:"password" env:"PASSWORD"` // } // // var cfg ConfigDatabase // // err := cleanenv.ReadConfig("config.yml", &cfg) // if err != nil { // ... // } func ReadConfig(path string, cfg interface{}) error { … }
IDE support
IDE support
None
является ли Godoc идеальным инструментом для документации?
THE UGLY
None
None
THE BAD
None
None
THE GOOD
None
None
Документация может быть очень подробной, однако абсолютно бесполезной
как писать хорошую документацию?
не пишите книгу пишите инструкцию
от общего к частному
явная точка входа
реальные примеры и советы по использованию
примеры!
примеры! примеры!
примеры! примеры! примеры!
None
// ExampleGetDescription_customHeaderText builds a description text from structure tags with
custom header s func ExampleGetDescription_customHeaderText() { type config struct { One int64 `env:"ONE" env-description:"first parameter"` Two float64 `env:"TWO" env-description:"second parameter"` Three string `env:"THREE" env-description:"third parameter"` } var cfg config header := "Custom header text:" text, err := cleanenv.GetDescription(&cfg, &header) if err != nil { panic(err) } fmt.Println(text) //Output: Custom header text: // ONE int64 // first parameter // TWO float64 // second parameter // THREE string // third parameter }
None
✍
ведь есть README.md?
нет поддержки Markdown противно
у меня приватный репо, зачем мне вообще надо?
None
полезные ссылки dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319 blog.golang.org/godoc
ilyakaznacheev