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
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

5. documentation
   for a code
   

   View Slide

6. View Slide

7. code v1.7.13
   docs v1.1.6
   

   View Slide

8. documentation
   as a code
   

   View Slide

9. JavaDoc
   JSDoc
   Python Docstring
   ABAPDoc
   Godoc
   

   View Slide

10. what Godoc is?
    

    View Slide

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 { … }
    

    View Slide

12. IDE support
    

    View Slide

13. IDE support
    

    View Slide

14. View Slide

15. 
    is Godoc a perfect
    documenting
    tool?
    

    View Slide

16. THE UGLY
    

    View Slide

17. View Slide

18. View Slide

19. THE BAD
    

    View Slide

20. View Slide

21. View Slide

22. THE GOOD
    

    View Slide

23. View Slide

24. View Slide

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

    View Slide

26. how to
    write good
    documentation?
    

    View Slide

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

    View Slide

28. From abstract to specific
    

    View Slide

29. Explicit entry point
    

    View Slide

30. Real use-cases and tips
    

    View Slide

31. Examples!
    

    View Slide

32. Examples!
    Examples!
    

    View Slide

33. Examples!
    Examples!
    Examples!
    

    View Slide

34. View Slide

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
    }
    

    View Slide

36. View Slide

37. View Slide

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

    View Slide

39. ilyakaznacheev
    

    View Slide