Large repo switched to new go1.19 doc comments

go 1.19 introduces new doc comments formatting features, allowing to easily insert links and lists.

Details are described here → https://go.dev/doc/comment

Links & lists

Links are probably the most interesting feature as they permit to enhance the documentation by providing users hints without inserting full URL as one needs before:

// The allowed shortcut operators follow:
//   - [Empty]    → $^Empty
//   - [Ignore]   → $^Ignore
//   - [NaN]      → $^NaN
//   - [Nil]      → $^Nil
//   - [NotEmpty] → $^NotEmpty
//   - [NotNaN]   → $^NotNaN
//   - [NotNil]   → $^NotNil
//   - [NotZero]  → $^NotZero
//   - [Zero]     → $^Zero
//
// TypeBehind method returns the [reflect.Type] of the expectedJSON
// once JSON unmarshaled. So it can be bool, string, float64, []any,
// map[string]any or any in case expectedJSON is "null".
//
// See also [JSONPointer], [SubJSONOf] and [SuperJSONOf].

produces:

The listing feature is also used above. Before go 1.19, indented bullets were detected as a simple code block and were displayed with a monospaced font.

Links can reference local exported identifiers (like JSONPointer or SubJSONOf) as well as identifiers in other packages (like reflect.Type).

To produce links to other resources, one can now define links using the Markdown shortcut reference link format (without the optional title text) as in:

// MultipartBody is a body of a multipart/form-data HTTP request (by
// default, or any other multipart/… body, see MediaType field) as
// defined in [RFC 2046] to be used as a [io.Reader] body of
// [http.Request] and so compliant with [RFC 2388]. It implements
// [io.Reader] and can only be read once. See [PostMultipartFormData]
// and [TestAPI.PostMultipartFormData] for examples of use.
//
// [RFC 2046]: https://tools.ietf.org/html/rfc2046
// [RFC 2388]: https://tools.ietf.org/html/rfc2388

producing:

Note that these shortcuts are scoped to the comment they are declared in.

Full example

To see the result on a large repository, I adapted the comments of go-testdeep to fully take advantage of these new features.

You can see the result for each impacted package:

• https://pkg.go.dev/github.com/maxatome/go-testdeep/td
• https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdhttp
• https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdsuite
• https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdutil

A few remarks

It seems that pkg.go.dev hasn't handled [links] in lists yet. I say "yet", because the last version of godoc handles them properly. So I suppose it will be fixed soon.

Struct fields links work for standard packages, but not for local/current one. For example [http.Cookie.Raw] produces a link to the Raw field of Cookie in net/http package (example), but in go-testdeep td package [ContextConfig.RootName] remains intact and so is not changed into a link, even when using the last version of godoc.

Links are not handled in var or const comments when a single keyword groups several declarations:

// DefaultContextConfig is the default configuration used to render
// tests failures. If overridden, new settings will impact all Cmp*
// functions and [*T] methods (if not specifically configured.)
var DefaultContextConfig = ContextConfig{…}

is OK, but:

var (
  // DefaultContextConfig is the default configuration used to render
  // tests failures. If overridden, new settings will impact all Cmp*
  // functions and [*T] methods (if not specifically configured.)
  DefaultContextConfig = ContextConfig{
)

does not work, [*T] remains intact in generated godoc. It is too bad.

Some ideas

[x] could be a builtin pointing to https://pkg.go.dev/builtin#x, like error for example, for all native types, as we see them in signatures.

It could be cool to have shortcut reference links global to the package, perhaps in the package doc itself. It would avoid to declare in each comment the same shortcut again and again.

It can be interesting that the shortcut reference links accept indirect URLs. For example, in td I often talk about Cmp* functions. Each time, I would like to reference Cmp function (the first one of the Cmp* serie). To do it, I have to set the full URL in the shortcut:

// [Cmp*]: https://pkg.go.dev/github.com/maxatome/go-testdeep/td#Cmp

while simply using:

// [Cmp*]: Cmp

would avoid referencing pkg.go.dev as [Cmp] does elsewhere.

Conclusion

The result of using these new features is pretty cool. Let's hope that package authors will enhance their docs to help their users to easily discover their APIs, in a more friendly way.