Godoc documentation not outputting lists

问题

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.

回答1:

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.

来源：https://stackoverflow.com/questions/52744468/godoc-documentation-not-outputting-lists

标签

godoc