Godoc documentation not outputting lists

Question

I have, throughout the project I'm responsible for testing and documenting, created documentation for the functions and methods, in the following format:

// CheckPermissionArray checks that values is an array that contains the `expectedValue`
//
// Parameters:
//
// - `values` : the array to check
// - `expectedValue` : the value to search for
//
// Returns:
//
// - an error iff `expectedValue` is not in `values`

The boss and other programmers approve of this format, but the problem is that godoc doesn't recognize the list:

Is there a way to get the list to be recognized?

Visual Studio Code was, to a point, recognizing this documentation just fine, albeit a bit buggy.

Answer 1

This might change in the future with "https://github.com/golang/go/issues/51082" (Feb. 2022)
March 2022: the proposal is accepted, and part of it is in Go 1.19 beta1 (June 2022).

This proposal improves support for headings, lists, and links in Go doc comments, while remaining backwards compatible with existing comments.

It includes a new package, go/doc/comment, exposing a parsed syntax tree for doc comments, and it includes changes to go/printer and therefore gofmt to format doc comments in a standard way.

For example, existing lists reformat from the display on the left to the one on the right:

---

June 2022: CL 415174 adds:

The proposed (#51082) new go doc comment additions supports lists, links, and doc links, but does not support links and doc links inside lists, so implements this.

This implements #53610

Example:

//  - Do this, or...
//  - See [RFC], or...
//
//    [RFC]: https://datatracker.ietf.org/doc/html/rfc2616
//  - Something else

Answer 2

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.