Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: links in package godocs don't work in the directory view #57964

Open
mvdan opened this issue Jan 23, 2023 · 7 comments
Open

x/pkgsite: links in package godocs don't work in the directory view #57964

mvdan opened this issue Jan 23, 2023 · 7 comments

Comments

@mvdan
Copy link
Member

mvdan commented Jan 23, 2023

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

image

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

@mvdan mvdan added the pkgsite label Jan 23, 2023
@gopherbot gopherbot added this to the Unreleased milestone Jan 23, 2023
@findleyr
Copy link
Contributor

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
Copy link
Member Author

mvdan commented Jan 26, 2023

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
Copy link
Contributor

@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
Copy link
Contributor

rsc commented Jan 26, 2023

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
Copy link
Contributor

rsc commented Jan 26, 2023

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
Copy link
Contributor

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

Want to send a CL, or shall I?

@rsc
Copy link
Contributor

rsc commented Jan 27, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants