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

Comments

Projects
None yet
3 participants
@dmitshur
Copy link
Member

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

@dmitshur dmitshur added this to the Go1.14 milestone May 9, 2019

@griesemer

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.