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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  4. documentation
    for a code

    View full-size slide

  5. code v1.7.13
    docs v1.1.6

    View full-size slide

  6. documentation
    as a code

    View full-size slide

  7. JavaDoc
    JSDoc
    Python Docstring
    ABAPDoc
    Godoc

    View full-size slide

  8. what Godoc is?

    View full-size slide

  9. 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 full-size slide


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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  17. примеры!

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  20. // 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  25. ilyakaznacheev

    View full-size slide