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

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

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

Cee15b0246090c00f7de03e0a976f3ed?s=128

Ilya Kaznacheev

July 18, 2020
Tweet

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. ведь есть README.md?

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

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

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

  42. ilyakaznacheev