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
Tweet

More Decks by Ilya Kaznacheev

Other Decks in Programming

Transcript

  1. Ilya Kaznacheev
    Remote Backend SWE
    Founder of Golang Voronezh
    Host of Z-Namespace podcast
    Organizer of conference and meetups
    Coffee geek

    View full-size slide

  2. Golang Voronezh
    - ~30 active members
    - meetups
    - events for beginners
    - open & friendly

    View full-size slide

  3. godoc
    - a tool for built-in documentation in Go sources
    - a web site for Go package documentation hosting

    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. is Godoc a perfect
    documenting
    tool?

    View full-size slide

  11. The documentation can be very
    detailed, but completely useless

    View full-size slide

  12. how to
    write good
    documentation?

    View full-size slide

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

    View full-size slide

  14. From abstract to specific

    View full-size slide

  15. Explicit entry point

    View full-size slide

  16. Real use-cases and tips

    View full-size slide

  17. Examples!
    Examples!

    View full-size slide

  18. Examples!
    Examples!
    Examples!

    View full-size slide

  19. // 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

  20. helpful links
    dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319
    blog.golang.org/godoc

    View full-size slide

  21. ilyakaznacheev

    View full-size slide