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

Transcript

1. GODOC
   

   View Slide

2. Ilya Kaznacheev
   Remote Backend SWE
   Основатель Golang Voronezh
   Соавтор Z-Namespace podcast
   Организатор конференций и митапов
   Любитель кофе
   

   View Slide

3. Golang Voronezh
   - ~30 активных участников
   - митапы
   - мероприятия для новичков
   

   View Slide

4. - инструмент для встроенной в код документации
   - сайт для хостинга документации публичных проектов
   godoc
   

   View Slide

5. documentation
   for a code
   

   View Slide

6. View Slide

7. code v1.7.13
   docs v1.1.6
   

   View Slide

8. documentation
   as a code
   

   View Slide

9. JavaDoc
   JSDoc
   Python Docstring
   ABAPDoc
   Godoc
   

   View Slide

10. what Godoc is?
    

    View Slide

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 { … }
    

    View Slide

12. IDE support
    

    View Slide

13. IDE support
    

    View Slide

14. View Slide

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

    View Slide

16. THE UGLY
    

    View Slide

17. View Slide

18. View Slide

19. THE BAD
    

    View Slide

20. View Slide

21. View Slide

22. THE GOOD
    

    View Slide

23. View Slide

24. View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

31. примеры!
    

    View Slide

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

    View Slide

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

    View Slide

34. View Slide

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
    }
    

    View Slide

36. View Slide

37. ✍
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

41. View Slide

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

    View Slide

43. ilyakaznacheev
    

    View Slide