Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(369)

Issue 5437056: code review 5437056: go/doc: Detect headings in comments and format them as ... (Closed)

Can't Edit
Can't Publish+Mail
Start Review
Created:
12 years, 8 months ago by volker.dobler
Modified:
12 years, 7 months ago
Reviewers:
CC:
jnml, gri, adg, rsc, r2, golang-dev
Visibility:
Public.

Description

go/doc: Detect headings in comments and format them as h3 in html. To structure larger sections of comments in html output headings are detected in comments and formated as h3 in the generated html. A simple heuristic is used to detect headings in comments: A heading is a non-blank, non-indented line preceded by a blank line. It is followed by a blank and a non-blank, non-indented line. A heading must start with an uppercase letter and end with a letter, digit or a colon. A heading may not contain punctuation characters.

Patch Set 1 #

Patch Set 2 : diff -r 90bf4e91689b https://go.googlecode.com/hg/ #

Patch Set 3 : diff -r 90bf4e91689b https://go.googlecode.com/hg/ #

Total comments: 8

Patch Set 4 : diff -r d0323ff8f6de https://go.googlecode.com/hg/ #

Total comments: 14

Patch Set 5 : diff -r 9597efd7331a https://go.googlecode.com/hg/ #

Total comments: 3

Patch Set 6 : diff -r 9597efd7331a https://go.googlecode.com/hg/ #

Total comments: 6

Patch Set 7 : diff -r 9597efd7331a https://go.googlecode.com/hg/ #

Total comments: 8

Patch Set 8 : diff -r 9597efd7331a https://go.googlecode.com/hg/ #

Total comments: 6

Patch Set 9 : diff -r 1a849cf27418 https://go.googlecode.com/hg/ #

Total comments: 37

Patch Set 10 : diff -r 684f7bc2bf99 https://go.googlecode.com/hg/ #

Patch Set 11 : diff -r 684f7bc2bf99 https://go.googlecode.com/hg/ #

Total comments: 10

Patch Set 12 : diff -r c93109f5d3ca https://go.googlecode.com/hg/ #

Unified diffs Side-by-side diffs Delta from patch set Stats (+175 lines, -0 lines) Patch
M doc/all.css View 1 2 3 4 5 6 7 8 1 chunk +3 lines, -0 lines 0 comments Download
M src/pkg/go/doc/Makefile View 1 2 3 4 5 6 7 8 9 10 11 1 chunk +6 lines, -0 lines 0 comments Download
M src/pkg/go/doc/comment.go View 1 2 3 4 5 6 7 8 9 10 11 7 chunks +74 lines, -0 lines 0 comments Download
A src/pkg/go/doc/comment_test.go View 1 2 3 4 5 6 7 8 9 1 chunk +39 lines, -0 lines 0 comments Download
A src/pkg/go/doc/headscan.go View 1 2 3 4 5 6 7 8 9 10 11 1 chunk +53 lines, -0 lines 0 comments Download

Messages

Total messages: 52
volker.dobler
Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com), I'd like you to review this change to https://go.googlecode.com/hg/
12 years, 8 months ago (2011-11-24 11:57:26 UTC) #1
jnml
On 2011/11/24 11:57:26, volker.dobler wrote: > I'd like you to review this change to Excerpts ...
12 years, 8 months ago (2011-11-24 18:13:14 UTC) #2
gri
Some comments. But I like to think about this some more before we are going ...
12 years, 8 months ago (2011-11-25 20:41:11 UTC) #3
volker.dobler
Hello golang-dev@googlegroups.com, jan.mercl@nic.cz, gri@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 8 months ago (2011-11-28 00:01:51 UTC) #4
volker.dobler
http://codereview.appspot.com/5437056/diff/5001/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/5001/src/pkg/go/doc/comment.go#newcode282 src/pkg/go/doc/comment.go:282: switch s[len(s)-2] { On 2011/11/25 20:41:11, gri wrote: > ...
12 years, 8 months ago (2011-11-28 00:04:30 UTC) #5
adg
http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go#newcode275 src/pkg/go/doc/comment.go:275: const maxWordsInHeading = 5 // a heading has at ...
12 years, 8 months ago (2011-11-28 05:33:44 UTC) #6
adg
http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go#newcode287 src/pkg/go/doc/comment.go:287: // len(s) >= 2 On 2011/11/28 05:33:44, adg wrote: ...
12 years, 8 months ago (2011-11-28 05:34:41 UTC) #7
volker.dobler
Hello golang-dev@googlegroups.com, jan.mercl@nic.cz, gri@golang.org, adg@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 8 months ago (2011-11-28 09:01:16 UTC) #8
volker.dobler
http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go#newcode275 src/pkg/go/doc/comment.go:275: const maxWordsInHeading = 5 // a heading has at ...
12 years, 8 months ago (2011-11-28 09:02:24 UTC) #9
adg
On 28 November 2011 20:02, <dr.volker.dobler@gmail.com> wrote: > > http://codereview.appspot.com/5437056/diff/3005/src/pkg/go/doc/comment.go > File src/pkg/go/doc/comment.go (right): > ...
12 years, 8 months ago (2011-11-28 09:44:41 UTC) #10
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 8 months ago (2011-11-28 09:57:50 UTC) #11
volker.dobler
On 2011/11/28 09:44:41, adg wrote: > On 28 November 2011 20:02, <mailto:dr.volker.dobler@gmail.com> wrote: > > ...
12 years, 8 months ago (2011-11-28 10:01:06 UTC) #12
adg
http://codereview.appspot.com/5437056/diff/8001/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/8001/src/pkg/go/doc/comment.go#newcode173 src/pkg/go/doc/comment.go:173: html_h = []byte("<h3>") // "Overview", "Constants", function and types ...
12 years, 8 months ago (2011-11-28 10:01:17 UTC) #13
adg
http://codereview.appspot.com/5437056/diff/11001/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/11001/src/pkg/go/doc/comment.go#newcode375 src/pkg/go/doc/comment.go:375: // current line is nonempyt, preceeded by two blank ...
12 years, 8 months ago (2011-11-28 10:02:07 UTC) #14
adg
http://codereview.appspot.com/5437056/diff/11001/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/11001/src/pkg/go/doc/comment.go#newcode285 src/pkg/go/doc/comment.go:285: line = line[:len(line)-1] What you've done here is probably ...
12 years, 8 months ago (2011-11-28 10:04:10 UTC) #15
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 8 months ago (2011-11-28 11:07:22 UTC) #16
volker.dobler
http://codereview.appspot.com/5437056/diff/11001/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/11001/src/pkg/go/doc/comment.go#newcode285 src/pkg/go/doc/comment.go:285: line = line[:len(line)-1] On 2011/11/28 10:04:10, adg wrote: > ...
12 years, 8 months ago (2011-11-28 11:07:42 UTC) #17
rsc
Do you have some examples of before/after HTML that we can view? Thanks. http://codereview.appspot.com/5437056/diff/11004/src/pkg/go/doc/comment.go File ...
12 years, 8 months ago (2011-11-28 17:15:53 UTC) #18
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org, rsc@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 8 months ago (2011-11-28 18:59:26 UTC) #19
volker.dobler
On 11/28/11, rsc@golang.org <rsc@golang.org> wrote: > Do you have some examples of before/after HTML that ...
12 years, 8 months ago (2011-11-28 19:19:43 UTC) #20
volker.dobler
http://codereview.appspot.com/5437056/diff/11004/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/11004/src/pkg/go/doc/comment.go#newcode70 src/pkg/go/doc/comment.go:70: // interior blank lines to at most two blank ...
12 years, 8 months ago (2011-11-28 19:20:32 UTC) #21
rsc
On Mon, Nov 28, 2011 at 14:20, <dr.volker.dobler@gmail.com> wrote: > Keeping two lines here helps ...
12 years, 8 months ago (2011-11-28 19:23:30 UTC) #22
volker.dobler
Just running Andrew's script (tmp/headscan) produces: volker@linuxvm:~/go/src $ ../../tmp/headscan 2011/11/28 20:32:35 cmd/goinstall: <h3>Remote Repositories</h3> 2011/11/28 ...
12 years, 8 months ago (2011-11-28 19:36:18 UTC) #23
rsc
Thanks, seems reasonable to me. Leaving for Andrew.
12 years, 8 months ago (2011-11-28 19:38:01 UTC) #24
adg
Looking good. One last thing. http://codereview.appspot.com/5437056/diff/13002/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/13002/src/pkg/go/doc/comment.go#newcode374 src/pkg/go/doc/comment.go:374: // lines and followed ...
12 years, 8 months ago (2011-11-28 22:47:04 UTC) #25
adg
Also please update the CL description to reflect the decisions made. (hg change 5437056)
12 years, 8 months ago (2011-11-28 22:47:47 UTC) #26
gri
Hold on, please. I am not yet convinced. The heuristic as is leads people to ...
12 years, 8 months ago (2011-11-28 22:52:48 UTC) #27
gri
http://codereview.appspot.com/5437056/diff/13002/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/13002/src/pkg/go/doc/comment.go#newcode308 src/pkg/go/doc/comment.go:308: // Enclose headings with <h3> tags. s/<h3>/header/ so the ...
12 years, 8 months ago (2011-11-28 22:57:08 UTC) #28
adg
http://codereview.appspot.com/5437056/diff/13002/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/13002/src/pkg/go/doc/comment.go#newcode372 src/pkg/go/doc/comment.go:372: if blanks == 2 && len(lines) >= i+2 && ...
12 years, 8 months ago (2011-11-28 23:01:54 UTC) #29
gri
Here's a summary of a longer discussion between Andrew and me: We both agree that ...
12 years, 8 months ago (2011-11-29 00:17:19 UTC) #30
volker.dobler
On Tue, Nov 29, 2011 at 1:17 AM, Robert Griesemer <gri@golang.org> wrote: > Here's a ...
12 years, 8 months ago (2011-11-29 05:54:33 UTC) #31
gri
On Mon, Nov 28, 2011 at 9:54 PM, Volker Dobler <dr.volker.dobler@gmail.com> wrote: > Regarding the ...
12 years, 8 months ago (2011-11-29 06:00:04 UTC) #32
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org, rsc@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 8 months ago (2011-11-29 22:14:03 UTC) #33
gri
Much better. This heuristic can be relatively easily refined as necessary. Andrew's headscan file is ...
12 years, 7 months ago (2011-11-30 20:13:54 UTC) #34
gri
PS: Please also update the CL description (remove the paragraph "Review Note"). - gri On ...
12 years, 7 months ago (2011-11-30 20:28:12 UTC) #35
volker.dobler
I was wondering wether src/pkg/gp/doc was the right place for the headscan tool. But it ...
12 years, 7 months ago (2011-11-30 22:42:35 UTC) #36
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org, rsc@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 7 months ago (2011-11-30 22:49:37 UTC) #37
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org, rsc@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 7 months ago (2011-11-30 22:50:26 UTC) #38
adg
http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/headscan.go File src/pkg/go/doc/headscan.go (right): http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/headscan.go#newcode39 src/pkg/go/doc/headscan.go:39: i := bytes.Index(b, []byte("<h3>")) If you use <h4> now ...
12 years, 7 months ago (2011-11-30 23:06:46 UTC) #39
gri
On Wed, Nov 30, 2011 at 3:06 PM, <adg@golang.org> wrote: > http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/headscan.go#newcode39 > src/pkg/go/doc/headscan.go:39: i ...
12 years, 7 months ago (2011-11-30 23:12:45 UTC) #40
gri
Almost there. Some minor issues and a bug. - gri http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/comment.go#newcode276 ...
12 years, 7 months ago (2011-11-30 23:24:23 UTC) #41
gri
Also: Please fix headscan.go - it doesn't compile anymore (still uses the old-style os.FileInfo). - ...
12 years, 7 months ago (2011-11-30 23:26:33 UTC) #42
jnml
On 2011/11/30 23:24:23, gri wrote: > Almost there. Some minor issues and a bug. Is ...
12 years, 7 months ago (2011-12-01 08:32:34 UTC) #43
volker.dobler
Hello jan.mercl@nic.cz, gri@golang.org, adg@golang.org, rsc@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
12 years, 7 months ago (2011-12-01 09:03:41 UTC) #44
volker.dobler
http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/comment.go File src/pkg/go/doc/comment.go (right): http://codereview.appspot.com/5437056/diff/6/src/pkg/go/doc/comment.go#newcode276 src/pkg/go/doc/comment.go:276: // eading returns the (possibly trimmed) line if it ...
12 years, 7 months ago (2011-12-01 09:03:49 UTC) #45
volker.dobler
On Thu, Dec 1, 2011 at 9:32 AM, <jan.mercl@nic.cz> wrote: > > Is there any ...
12 years, 7 months ago (2011-12-01 09:27:04 UTC) #46
r2
On Dec 1, 2011, at 12:32 AM, jan.mercl@nic.cz wrote: > On 2011/11/30 23:24:23, gri wrote: ...
12 years, 7 months ago (2011-12-01 16:54:17 UTC) #47
rsc
Just to add to what Rob said, the key point about Go comments in contrast ...
12 years, 7 months ago (2011-12-01 17:01:06 UTC) #48
gri
Agreed. I think the current CL is close: It just does the right thing w/o ...
12 years, 7 months ago (2011-12-01 17:04:42 UTC) #49
jnml
On 2011/12/01 16:54:17, r2 wrote: > Gri and I had a long talk about it ...
12 years, 7 months ago (2011-12-01 17:05:21 UTC) #50
gri
LGTM. Thanks for bearing w/ me. - gri
12 years, 7 months ago (2011-12-01 17:45:18 UTC) #51
gri
12 years, 7 months ago (2011-12-01 17:50:01 UTC) #52
*** Submitted as http://code.google.com/p/go/source/detail?r=deeec5c15f88 ***

go/doc: Detect headings in comments and format them as h3 in html.

To structure larger sections of comments in html output headings
are detected in comments and formated as h3 in the generated html.
A simple heuristic is used to detect headings in comments:
A heading is a non-blank, non-indented line preceded by a blank
line. It is followed by a blank and a non-blank, non-indented line.
A heading must start with an uppercase letter and end with a letter,
digit or a colon.  A heading may not contain punctuation characters.

R=jan.mercl, gri, adg, rsc, r
CC=golang-dev
http://codereview.appspot.com/5437056

Committer: Robert Griesemer <gri@golang.org>
Sign in to reply to this message.

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b