> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Go Documentation Comment
Go documentation comments are specially formatted comments placed immediately preceding a package, function, type, or variable declaration, without any intervening blank lines. The Go parser associates these comments with the subsequent Abstract Syntax Tree (AST) node, allowing tools like `go doc` and the `pkg.go.dev` portal to extract and render structured technical documentation.
## Syntax and Association
To associate a comment with a declaration, it must be contiguous with the declaration. Standard convention dictates using single-line comments (`//`) rather than block comments (`/* ... */`), even for multi-line documentation.
The first sentence of the comment must be a single, complete summary sentence that begins with the exact name of the declared entity.
```go theme={"dark"}
// Server represents an HTTP server handling client requests.
// It maintains the connection pool and routing table.
type Server struct {
// ...
}
```
If a blank line separates the comment from the declaration, the Go toolchain treats it as a detached package-level comment, and it will not appear in the generated documentation for that entity.
```go theme={"dark"}
// This comment is detached and will NOT be associated with Start.
func Start() {}
```
## Formatting Rules (Go 1.19+)
The Go documentation parser recognizes a specific subset of formatting directives, heavily expanded in Go 1.19 to include standard structural elements.
**Paragraphs**
Paragraphs are separated by a blank comment line (a line containing only `//`).
```go theme={"dark"}
// Parse evaluates the input string and returns an AST.
//
// Parse will return a SyntaxError if the input is malformed.
func Parse(input string) error {
return nil
}
```
**Headings**
Headings are created using a hash symbol (`#`) followed by a space. The heading must be separated from surrounding paragraphs by blank comment lines.
```go theme={"dark"}
// # Error Handling
//
// All errors returned by this package wrap the base Error type.
```
**Preformatted Text (Code Blocks)**
Text indented by at least one space or tab relative to the surrounding comment text is treated as a preformatted block. It is rendered in a monospace font and preserves exact whitespace.
```go theme={"dark"}
type Command struct{}
// Execute runs the command. Example:
//
// cmd := NewCommand()
// cmd.Execute()
func (c *Command) Execute() {}
```
**Lists**
The parser recognizes unordered lists using dashes (`-`) or asterisks (`*`), and ordered lists using numbers (`1.`). List items must be indented, and the list must be separated from preceding paragraphs by a blank comment line.
```go theme={"dark"}
// Supported modes:
//
// - ModeRead: Opens the file for reading.
// - ModeWrite: Opens the file for writing.
```
**Links**
Links are declared using bracket notation. To maintain plain-text readability, Go does not support inline Markdown links (e.g., `[Text](URL)`). Instead, it supports documentation links, automatic URL linking, and reference links.
* **Doc Links:** `[Name]` links to the documentation of the entity named `Name` within the same package, or an imported package (e.g., `[fmt.Println]`).
* **URL Links:** Raw URLs are automatically linked. For custom display text, use a reference link by placing `[Text]` in the comment and defining the destination on a separate line using `[Text]: URL`.
```go theme={"dark"}
// Write outputs the data to the [io.Writer].
// For more details, see the [official specification].
//
// [official specification]: https://example.com/spec
func Write() {}
```
## Directives
Documentation comments support specific toolchain directives. The most prominent is the `Deprecated:` marker. It must begin with `Deprecated:` followed by an explanation and an alternative recommendation. The `go doc` tool and IDEs parse this to visually strike through the entity and warn developers.
```go theme={"dark"}
// CalculateTotal computes the sum of the slice.
//
// Deprecated: Use [Sum] instead. CalculateTotal does not handle overflows.
func CalculateTotal(data []int) int {
return 0
}
```
## Package Documentation
To document an entire package, the documentation comment must be placed immediately above the `package` clause. For large packages, this is conventionally isolated in a dedicated file named `doc.go`.
```go theme={"dark"}
// Package math provides basic constants and mathematical functions.
//
// # Precision
//
// All computations are performed using IEEE 754 64-bit floating-point numbers.
package math
```
Tired of Poor Go Skills? Fix That With Deep Grasping!
Learn More
