神刀安全网

godoc: Tips & Tricks

godoc: Tips & Tricks

Go has a great emphasis on simple, no-nonsense documentation right out of the box. Rather than using an existing format (like Markdown ) where formatting is often explicitly stated godoc uses many implicit rules to extract quality documentation from really plain text so that you can spend less time formatting your documentation and more time writing it.

godoc can produce docs in several formats, such as text (similar to a man page ) but the most common one you will come across is the HTML version .

In this article I will be focusing on how the formatting is produced rather than how to use the godoc command-line tool itself. It has a whole bunch of other options that are well documented .

Package Overview & License

godoc: Tips & Tricks

// Copyright Some Company Corp. // All Rights Reserved  // Here is where we explain the package. // Some other stuff. package doc

Package level documentation must be in a continuous comment immediately preceding the package statement. If there is a blank line between the comment and the package statement it will be discarded. This is how you add comments that should or should not be included in the general package documentation.

The first sentence is important because it is automatically extracted as the brief overview for the package when listing all the packages, like:

godoc: Tips & Tricks

Since a package can be made up of more than one file you can spread the package documentation across files and godoc will merge all of these into the same Overview block. The order, as far as I’m aware, is not guaranteed to be predicable. But it does offer a nice way to document parts of the package in the individual files that make sense.

Alternatively, you can add a file to your package which contains no code but the complete package documentation and a single package statement if that makes sense too.

Paragraphs

To make wrapping long continuing lines easier godoc will assume that all subsequent lines are part of the same paragraph. However, you can explicitly separate paragraphs with a blank line (you still need to put the // so that the comment is one continuous block). If you’re familiar with Markdown then this works the same way.

godoc: Tips & Tricks

// Here is where we explain the package. // // Some other stuff. package doc

Constants

Many packages contain exported constants. Those that are exported are very important to document. This can be one of two ways, the first is to document all the const values independently:

godoc: Tips & Tricks

// This is the host const Host = "example.com"  // The port number for the host. const Port = 1234

If you have const values that are related it might be better to include them in a single const declaration:

godoc: Tips & Tricks

// This appears under the const. const (     // This causes Foo to happen.     OptionFoo = 1      // This causes Bar to happen.     OptionBar = 2      // Documented, but not visible.     optionSecret = 3 )

Methods

// Math stuff.  // Absolute value. func Abs(x float64) float64 { }  // Sine value. func Sin(x float64) float64 { }  // Internal stuff.  // Docs are important even for internal stuff. func secretMethod() { }

Make sure the comment is immediately preceding the method (like the the package ) otherwise godoc will not include it in the output:

godoc: Tips & Tricks

Only exported methods are included in the documentation:

godoc: Tips & Tricks

Headings & Sections

Go is sensitive to things that look like (or don’t look like) sentences. godoc recognises a line that starts with a capital letter and does not end in a full stop as a heading.

godoc: Tips & Tricks

// Here is where we explain the package. // // See Also // // Some other stuff. package doc

Code Blocks

Code blocks let you add inline-code examples. The are identified as line that starts with at least one extra space (after the single space for // ):

// This is how to create a Hello World: //  fmt.Printf("Hello, World") // Or: //  fmt.Printf("Hello, " + name)

godoc: Tips & Tricks

Code blocks do not employ code-colouring, but this means they can be used for documenting any other non-go code, such as bash.

Links

Links are automatically recognised.

godoc: Tips & Tricks

// See https://godoc.org for more information.

Thank you for reading. I’d really appreciate any and all feedback, please leave your comments below or consider subscribing. Happy coding.

Elliot Chance –

I’m a data nerd and TDD enthusiast living in Sydney, Australia. I love exploring new technologies and working on modern ways to solve age old problems.

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » godoc: Tips & Tricks

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址