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

go/doc: Synopsis can return a sentence spanning multiple paragraphs and code blocks #31947

Open
dmitshur opened this issue May 9, 2019 · 2 comments
Milestone

Comments

@dmitshur
Copy link
Member

@dmitshur dmitshur commented May 9, 2019

The Synopsis function defines the logic to determine the synopsis, often used on package documentation. The logic is:

Synopsis returns a cleaned version of the first sentence in s. That sentence ends after the first period followed by space and not preceded by exactly one uppercase letter. The result string has no \n, \r, or \t characters and uses only single spaces between words. If s starts with any of the IllegalPrefixes, the result is the empty string.

Let "paragraph" mean a block of text separated from other text by a blank line (i.e., "\n\n"). The current synopsis logic means a sentence can span across multiple paragraphs. For example:

fmt.Println(doc.Synopsis(`This is a sentence that starts in the first paragraph

and it keeps going in the second paragraph

and ends in the third paragraph. This is the second sentence.`))

// Output: This is a sentence that starts in the first paragraph and it keeps going in the second paragraph and ends in the third paragraph.

(Playground link: https://play.golang.org/p/hSAetYyxkwa)

Perhaps we should consider changing the logic such that a sentence is not allowed to span multiple paragraphs.

From what I've observed, that is rarely used intentionally, but can happen unintentionally. For example, the current version of the github.com/rs/cors package has a very long synopsis that spans multiple paragraphs and includes code blocks:

$ go list -f '{{.Doc}}' github.com/rs/cors
Package cors is net/http handler to handle CORS related requests as defined by http://www.w3.org/TR/cors/ You can configure it by passing an option struct to cors.New: c := cors.New(cors.Options{ AllowedOrigins: []string{"foo.com"}, AllowedMethods: []string{http.MethodGet, http.MethodPost, http.MethodDelete}, AllowCredentials: true, }) Then insert the handler in the chain: handler = c.Handler(handler) See Options documentation for more options.

/cc @griesemer @julieqiu

Edit: Another one is github.com/peterhellberg/link:

$ go list -f '{{.Doc}}' github.com/peterhellberg/link
Package link parses Link headers used for pagination, as defined in RFC 5988 Installation Just go get the package: go get -u github.com/peterhellberg/link Usage A small usage example package main import ( "fmt" "net/http" "github.com/peterhellberg/link" ) func main() { for _, l := range link.Parse(`<https://example.com/?page=2>; rel="next"; foo="bar"`) { fmt.Printf("URI: %q, Rel: %q, Extra: %+v\n", l.URI, l.Rel, l.Extra) // URI: "https://example.com/?page=2", Rel: "next", Extra: map[foo:bar] } if resp, err := http.Get("https://api.github.com/search/code?q=Println+user:golang"); err == nil { for _, l := range link.ParseResponse(resp) { fmt.Printf("URI: %q, Rel: %q, Extra: %+v\n", l.URI, l.Rel, l.Extra) // URI: "https://api.github.com/search/code?q=Println+user%3Agolang&page=2", Rel: "next", Extra: map[] // URI: "https://api.github.com/search/code?q=Println+user%3Agolang&page=34", Rel: "last", Extra: map[] } } }
@dmitshur dmitshur added this to the Go1.14 milestone May 9, 2019
@griesemer
Copy link
Contributor

@griesemer griesemer commented May 10, 2019

Seems reasonable. Should perhaps run a small experiment and see if and which synopsis change, say for the std lib (I expect close to none to change).

@dmitshur
Copy link
Member Author

@dmitshur dmitshur commented May 10, 2019

Sounds good. To make progress on this issue, we should run that experiment and confirm the results are favorable. We should be able to include a corpus with a number of third-party packages in the experiment, in addition to the standard library packages.

@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.