code review 5676088: go/doc: move firstSentence into go/doc

go/doc: move firstSentence into go/doc

- renamed firstSentence -> Synopsis
- also deal with common abbreviations

[gri, 2012-02-18 01:06:25]

Hello rsc@golang.org (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://code.google.com/p/go

[rsc1, 2012-02-18 19:56:41]

http://codereview.appspot.com/5676088/diff/3001/src/cmd/godoc/dirtrees.go
File src/cmd/godoc/dirtrees.go (right):

http://codereview.appspot.com/5676088/diff/3001/src/cmd/godoc/dirtrees.go#new...
src/cmd/godoc/dirtrees.go:140: synopses[i] = t[0:doc.FirstSentenceLen(t)]
Why not use Synopsis here?

http://codereview.appspot.com/5676088/diff/3001/src/pkg/go/doc/synopsis.go
File src/pkg/go/doc/synopsis.go (right):

http://codereview.appspot.com/5676088/diff/3001/src/pkg/go/doc/synopsis.go#ne...
src/pkg/go/doc/synopsis.go:9: // FirstSentenceLen returns the length of the
first sentence in s.
Not clear this should be exported; maybe just Synopsis for now?

[gri, 2012-02-21 22:47:14]

PTAL.

Also improved firstSentenceLen by:

a) getting rid of pi (not needed)
b) being smarter about capital letters before the period: A single capital
letter is assumed to be part of an incomplete abbreviation, more than one is not
(as in "... ABI.")

http://codereview.appspot.com/5676088/diff/3001/src/cmd/godoc/dirtrees.go
File src/cmd/godoc/dirtrees.go (right):

http://codereview.appspot.com/5676088/diff/3001/src/cmd/godoc/dirtrees.go#new...
src/cmd/godoc/dirtrees.go:140: synopses[i] = t[0:doc.FirstSentenceLen(t)]
On 2012/02/18 19:56:41, rsc1 wrote:
> Why not use Synopsis here?

Done.

The original thinking here was to not allocate more text, but Synopsis is likely
to save memory by not keeping a pointer to a larger comment then the result.

http://codereview.appspot.com/5676088/diff/3001/src/pkg/go/doc/synopsis.go
File src/pkg/go/doc/synopsis.go (right):

http://codereview.appspot.com/5676088/diff/3001/src/pkg/go/doc/synopsis.go#ne...
src/pkg/go/doc/synopsis.go:9: // FirstSentenceLen returns the length of the
first sentence in s.
On 2012/02/18 19:56:41, rsc1 wrote:
> Not clear this should be exported; maybe just Synopsis for now?

Done.

[rsc, 2012-02-22 18:13:10]

LGTM

http://codereview.appspot.com/5676088/diff/7001/src/pkg/go/doc/synopsis.go
File src/pkg/go/doc/synopsis.go (right):

http://codereview.appspot.com/5676088/diff/7001/src/pkg/go/doc/synopsis.go#ne...
src/pkg/go/doc/synopsis.go:11: // not preceeded by exactly one uppercase letter.
s/ee/e/

[gri, 2012-02-22 18:49:38]

*** Submitted as http://code.google.com/p/go/source/detail?r=87824db308ec ***

go/doc: move firstSentence into go/doc

- renamed firstSentence -> Synopsis
- also deal with common abbreviations

R=rsc
CC=golang-dev
http://codereview.appspot.com/5676088