UPDATE: Go 1.19 beta1 has been released which adds support for several godoc improvements:
Doc Comments
Go 1.19 adds support for links, lists, and clearer headings in doc comments. As part of this change, gofmt now reformats doc comments to make their rendered meaning clearer. See “Go Doc Comments” for syntax details and descriptions of common mistakes now highlighted by gofmt.
Starting with Go 1.19, you can now add multiple types of lists, just indent the lines and use a marker such as *, +, - or • followed by a space or tab. You can also use numbered lists if you use numbers followed by a dot as the marker.
For example:
// This will be rendered as a list:
// - list item #1
// - list item #2
// - list item #3
Original answer follows.
As others noted, "lists" in comments will not be turned into HTML lists (such as <ol>, <ul>).
Recommended reading: Godoc: documenting Go code. Quoting from it:
Godoc is conceptually related to Python's Docstring and Java's Javadoc, but its design is simpler. The comments read by godoc are not language constructs (as with Docstring) nor must they have their own machine-readable syntax (as with Javadoc). Godoc comments are just good comments, the sort you would want to read even if godoc didn't exist.
Only the following transformations are performed when generating HTML docs:
There are a few formatting rules that Godoc uses when converting comments to HTML:
- Subsequent lines of text are considered part of the same paragraph; you must leave a blank line to separate paragraphs.
- Pre-formatted text must be indented relative to the surrounding comment text (see gob's doc.go for an example).
- URLs will be converted to HTML links; no special markup is necessary.
What you may do to "mimic" lists:
Using the following comment:
// Fv1 is just an example.
//
// Here's a list:
//
// -First item
//
// -Second item
//
// -Third item
//
// This is the closing line.
Results in the following output:
Fv1 is just an example.
Here's a list:
-First item
-Second item
-Third item
This is the closing line.
A slight variation giving better visual appearance is to use the bullet • character instead of the dash:
// Fv1 is just an example.
//
// Here's a list:
//
// • First item
//
// • Second item
//
// • Third item
//
// This is the closing line.
Results in (github.com/google/go-cmp uses it):
Fv1 is just an example.
Here's a list:
• First item
• Second item
• Third item
This is the closing line.
Or you may indent the list items (1 additional space is enough, but you can use more to your liking):
// Fv2 is just another example.
//
// Here's a list:
// -First item
// -Second item
// -Third item
//
// This is the closing line.
Which yields this in the generated doc:
Fv2 is just another example.
Here's a list:
-First item
-Second item
-Third item
This is the closing line.
You may create "nested" lists like this, identation is kept (as it will be a pre-formatted block):
// Fv3 is just another example.
//
// Here's a list:
// -First item
// -First.First item
// -First.Second item
// -Second item
//
// This is the closing line.
Result in doc:
Fv3 is just another example.
Here's a list:
-First item
-First.First item
-First.Second item
-Second item
This is the closing line.
