Godoc: the Good, the Bad and the Ugly

Godoc: the Good, the Bad and the Ugly

Godoc is a very powerful tool, but very few projects utilize its full potential.

It is often not used at all as a developer tool. Sometimes it is used, but only for short comments to describe what is already obvious. Much less often it is used to fully describe documentation for the code.

I will tell you how to use the full potential of godoc and write informative and related documentation with its help.

Cee15b0246090c00f7de03e0a976f3ed?s=128

Ilya Kaznacheev

July 07, 2020
Tweet

Transcript

  1. GODOC

  2. Ilya Kaznacheev Remote Backend SWE Founder of Golang Voronezh Host

    of Z-Namespace podcast Organizer of conference and meetups Coffee geek
  3. Golang Voronezh - ~30 active members - meetups - events

    for beginners - open & friendly
  4. godoc - a tool for built-in documentation in Go sources

    - a web site for Go package documentation hosting
  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. is Godoc a perfect documenting tool?

  16. THE UGLY

  17. None
  18. None
  19. THE BAD

  20. None
  21. None
  22. THE GOOD

  23. None
  24. None
  25. The documentation can be very detailed, but completely useless

  26. how to write good documentation?

  27. You don’t need a book You need a guide

  28. From abstract to specific

  29. Explicit entry point

  30. Real use-cases and tips

  31. Examples!

  32. Examples! Examples!

  33. Examples! Examples! Examples!

  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. None
  38. helpful links dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319 blog.golang.org/godoc

  39. ilyakaznacheev