Godoc: хороший, плохой, злой

Transcript

1. GODOC
2. Ilya Kaznacheev Remote Backend SWE Основатель Golang Voronezh Соавтор Z-Namespace podcast Организатор конференций и митапов Любитель кофе
3. Golang Voronezh - ~30 активных участников - митапы - мероприятия для новичков
4. - инструмент для встроенной в код документации - сайт для хостинга документации публичных проектов godoc
5. documentation for a code
7. code v1.7.13 docs v1.1.6
8. documentation as a code
9. JavaDoc JSDoc Python Docstring ABAPDoc Godoc
10. what Godoc is?
11. 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 { … }
12. IDE support
13. IDE support
15. является ли Godoc идеальным инструментом для документации?
16. THE UGLY
19. THE BAD
22. THE GOOD
25. Документация может быть очень подробной, однако абсолютно бесполезной
26. как писать хорошую документацию?
27. не пишите книгу пишите инструкцию
28. от общего к частному
29. явная точка входа
30. реальные примеры и советы по использованию
31. примеры!
32. примеры! примеры!
33. примеры! примеры! примеры!
35. // 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 }
37. ✍
38. ведь есть README.md?
39. нет поддержки Markdown противно
40. у меня приватный репо, зачем мне вообще надо?
42. полезные ссылки dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319 blog.golang.org/godoc
43. ilyakaznacheev