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.

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
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
15. is Godoc a perfect documenting tool?
16. THE UGLY
19. THE BAD
22. THE GOOD
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!
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 }
38. helpful links dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319 blog.golang.org/godoc
39. ilyakaznacheev