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

6. None

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

14. None

15. является ли Godoc идеальным инструментом для документации?

16. THE UGLY

17. None
18. None

19. THE BAD

20. None
21. None

22. THE GOOD

23. None
24. None

25. Документация может быть очень подробной, однако абсолютно бесполезной

26. как писать хорошую документацию?

27. не пишите книгу пишите инструкцию

28. от общего к частному

29. явная точка входа

30. реальные примеры и советы по использованию

31. примеры!

32. примеры! примеры!

33. примеры! примеры! примеры!

34. None

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 }
36. None

37. ✍

38. ведь есть README.md?

39. нет поддержки Markdown противно

40. у меня приватный репо, зачем мне вообще надо?

41. None

42. полезные ссылки dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319 blog.golang.org/godoc

43. ilyakaznacheev