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

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.

Ilya Kaznacheev

July 07, 2020

More Decks by Ilya Kaznacheev

Other Decks in Programming


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

    of Z-Namespace podcast Organizer of conference and meetups Coffee geek
  2. godoc - a tool for built-in documentation in Go sources

    - a web site for Go package documentation hosting
  3. 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 { … }
  4. // 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 }