x/pkgsite: links in package synopsis don't work in directory list

[mvdan]

What is the URL of the page with the issue?

https://pkg.go.dev/mvdan.cc/sh/v3@v3.6.1-0.20230123163603-8b4fb75c77da#section-directories

What is your user agent?

Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/109.0

Screenshot

What did you do?

Started using doc links in my godoc comments. Used a link to a package in another package's godoc.

What did you expect to see?

The link to render properly in all relevant pkg.go.dev pages.

What did you see instead?

It renders properly in the package itself: https://pkg.go.dev/mvdan.cc/sh/v3@v3.6.1-0.20230123163603-8b4fb75c77da/cmd/gosh

However, the link remains in its plaintext form in the directory view: https://pkg.go.dev/mvdan.cc/sh/v3@v3.6.1-0.20230123163603-8b4fb75c77da#section-directories

[findleyr]

This is using https://pkg.go.dev/go/doc#Package.Synopsis, which returns a string rather than markdown.

I'm not convinced we should change this. Synopses are served in many places where markdown/html doesn't work. IMO it may be better to avoid it in the first sentence of a package doc. We could of course add special handling to pkgsite, but then that would be enabling a convention that is problematic for other tools.

[mvdan]

Synopses are served in many places where markdown/html doesn't work. IMO it may be better to avoid it in the first sentence of a package doc.

That's fair enough, but is that convention documented anywhere? It's the first time I hear of a package godoc synopsis, and https://go.dev/doc/comment doesn't say anything about them or about avoiding links in them :)

[findleyr]

@rsc suspected that this may simply be a bug in go/doc: the Synopsis function should correctly translate link syntax into plaintext, dropping the '[]'s.

[rsc]

The tests in src/go/doc/comment_test.go look like doc.(*Package).Synopsis already drops the [ ] but the old top-level doc.Synopsis does not, because it doesn't have accurate information about which [ ] correspond to links. Perhaps pkgsite is using the old doc.Synopsis and should migrate to doc.(*Package).Synopsis?

[rsc]

In pkgsite, I found

// DocInfo returns information extracted from the package's documentation.
// This destroys p's AST; do not call any methods of p after it returns.
func (p *Package) DocInfo(ctx context.Context, innerPath string, sourceInfo *source.Info, modInfo *ModuleInfo) (
	synopsis string, imports []string, api []*internal.Symbol, err error) {
	// This is mostly copied from internal/fetch/fetch.go.
	defer derrors.Wrap(&err, "godoc.Package.DocInfo(%q, %q, %q)", modInfo.ModulePath, modInfo.ResolvedVersion, innerPath)

	p.renderCalled = true
	d, err := p.docPackage(innerPath, modInfo)
	if err != nil {
		return "", nil, nil, err
	}

	api, err = dochtml.GetSymbols(d, p.Fset)
	if err != nil {
		return "", nil, nil, err
	}
	return doc.Synopsis(d.Doc), cleanImports(d.Imports, d.ImportPath), api, nil
}

It looks like doc.Synopsis(d.Doc) should be d.Synopsis(d.Doc).

[findleyr]

@rsc thanks for looking into it. That looks right.

Want to send a CL, or shall I?

[rsc]

I'll leave the CL to you - it'll get done faster. Thanks.

[dolmen]

@findleyr Did this get fixed?

[mrngm]

@dolmen no changes since 2021 https://github.com/golang/pkgsite/blame/f26e1ab5cf5bf4cbc49868e8ff3e37b54bc89acb/internal/godoc/render.go#L59