| // Copyright 2012 The Go Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| package doc |
| |
| import ( |
| "go/doc/comment" |
| "strings" |
| "unicode" |
| ) |
| |
| // firstSentence returns the first sentence in s. |
| // The sentence ends after the first period followed by space and |
| // not preceded by exactly one uppercase letter. |
| func firstSentence(s string) string { |
| var ppp, pp, p rune |
| for i, q := range s { |
| if q == '\n' || q == '\r' || q == '\t' { |
| q = ' ' |
| } |
| if q == ' ' && p == '.' && (!unicode.IsUpper(pp) || unicode.IsUpper(ppp)) { |
| return s[:i] |
| } |
| if p == '。' || p == '.' { |
| return s[:i] |
| } |
| ppp, pp, p = pp, p, q |
| } |
| return s |
| } |
| |
| // Synopsis returns a cleaned version of the first sentence in text. |
| // |
| // Deprecated: New programs should use [Package.Synopsis] instead, |
| // which handles links in text properly. |
| func Synopsis(text string) string { |
| var p Package |
| return p.Synopsis(text) |
| } |
| |
| // IllegalPrefixes is a list of lower-case prefixes that identify |
| // a comment as not being a doc comment. |
| // This helps to avoid misinterpreting the common mistake |
| // of a copyright notice immediately before a package statement |
| // as being a doc comment. |
| var IllegalPrefixes = []string{ |
| "copyright", |
| "all rights", |
| "author", |
| } |
| |
| // Synopsis returns a cleaned version of the first sentence in text. |
| // That sentence ends after the first period followed by space and not |
| // preceded by exactly one uppercase letter, or at the first paragraph break. |
| // The result string has no \n, \r, or \t characters and uses only single |
| // spaces between words. If text starts with any of the IllegalPrefixes, |
| // the result is the empty string. |
| func (p *Package) Synopsis(text string) string { |
| text = firstSentence(text) |
| lower := strings.ToLower(text) |
| for _, prefix := range IllegalPrefixes { |
| if strings.HasPrefix(lower, prefix) { |
| return "" |
| } |
| } |
| pr := p.Printer() |
| pr.TextWidth = -1 |
| d := p.Parser().Parse(text) |
| if len(d.Content) == 0 { |
| return "" |
| } |
| if _, ok := d.Content[0].(*comment.Paragraph); !ok { |
| return "" |
| } |
| d.Content = d.Content[:1] // might be blank lines, code blocks, etc in “first sentence” |
| return strings.TrimSpace(string(pr.Text(d))) |
| } |