Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

Ilya Kaznacheev

July 18, 2020
Tweet

More Decks by Ilya Kaznacheev

Other Decks in Programming

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