Repository: go
Issue: go/doc: Synopsis can return a sentence spanning multiple paragraphs and code blocks
Labels: NeedsDecision

The [`Synopsis`](https://godoc.org/go/doc#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:

```Go
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[] } } }
```

**Edit 2:** Another one is `github.com/astaxie/beego/orm@v1.12.2`:

```
$ go list -f '{{.Doc}}' github.com/astaxie/beego/orm
Package orm provide ORM for MySQL/PostgreSQL/sqlite Simple Usage package main import ( "fmt" "github.com/astaxie/beego/orm" _ "github.com/go-sql-driver/mysql" // import your used driver ) // Model Struct type User struct { Id int `orm:"auto"` Name string `orm:"size(100)"` } func init() { orm.RegisterDataBase("default", "mysql", "root:root@/my_db?charset=utf8", 30) } func main() { o := orm.NewOrm() user := User{Name: "slene"} // insert id, err := o.Insert(&user) // update user.Name = "astaxie" num, err := o.Update(&user) // read one u := User{Id: user.Id} err = o.Read(&u) // delete num, err = o.Delete(&u) } more docs: http://beego.me/docs/mvc/model/overview.md
```