cmd/doc: truncate long lists of arguments

Some field-lists (especially in generated code) can be excessively long.
In the one-line printout, it does not make sense to print all elements
of the list if line-wrapping causes the "one-line" to become multi-line.

// Before:
var LongLine = newLongLine("someArgument1", "someArgument2", "someArgument3", "someArgument4", "someArgument5", "someArgument6", "someArgument7", "someArgument8")

// After:
var LongLine = newLongLine("someArgument1", "someArgument2", "someArgument3", "someArgument4", ...)

Change-Id: I4bbbe2dbd1d7be9f02d63431d213088c3dee332c
Reviewed-on: https://go-review.googlesource.com/36031
Run-TryBot: Joe Tsai <thebrokentoaster@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

src/cmd/doc/doc_test.go

@@ -71,6 +71,7 @@ var tests = []test{
 			`const MultiLineConst = ...`,                                   // Multi line constant.
 			`var MultiLineVar = map\[struct{ ... }\]struct{ ... }{ ... }`,  // Multi line variable.
 			`func MultiLineFunc\(x interface{ ... }\) \(r struct{ ... }\)`, // Multi line function.
+			`var LongLine = newLongLine\(("someArgument[1-4]", ){4}...\)`,  // Long list of arguments.
 			`type T1 = T2`, // Type alias
 		},
 		[]string{
@@ -90,7 +91,8 @@ var tests = []test{
 			`unexportedTypedConstant`,           // No unexported typed constant.
 			`Field`,                             // No fields.
 			`Method`,                            // No methods.
-			`type T1 T2`, // Type alias does not display as type declaration.
+			`someArgument[5-8]`,                 // No truncated arguments.
+			`type T1 T2`,                        // Type alias does not display as type declaration.
 		},
 	},
 	// Package dump -u
@@ -270,7 +272,7 @@ var tests = []test{
 	// Type T1 dump (alias).
 	{
 		"type T1",
-		[]string{p+".T1"},
+		[]string{p + ".T1"},
 		[]string{
 			`type T1 = T2`,
 		},

src/cmd/doc/pkg.go

@@ -281,11 +281,11 @@ func (pkg *Package) oneLineNodeDepth(node ast.Node, depth int) string {
 			}
 		}
 
-		param := strings.Join(params, ", ")
+		param := joinStrings(params)
 		if len(results) == 0 {
 			return fmt.Sprintf("func(%s)", param)
 		}
-		result := strings.Join(results, ", ")
+		result := joinStrings(results)
 		if !needParens {
 			return fmt.Sprintf("func(%s) %s", param, result)
 		}
@@ -338,7 +338,7 @@ func (pkg *Package) oneLineNodeDepth(node ast.Node, depth int) string {
 		for _, arg := range n.Args {
 			args = append(args, pkg.oneLineNodeDepth(arg, depth))
 		}
-		return fmt.Sprintf("%s(%s)", fnc, strings.Join(args, ", "))
+		return fmt.Sprintf("%s(%s)", fnc, joinStrings(args))
 
 	case *ast.UnaryExpr:
 		return fmt.Sprintf("%s%s", n.Op, pkg.oneLineNodeDepth(n.X, depth))
@@ -367,7 +367,21 @@ func (pkg *Package) oneLineField(field *ast.Field, depth int) string {
 	if len(names) == 0 {
 		return pkg.oneLineNodeDepth(field.Type, depth)
 	}
-	return strings.Join(names, ", ") + " " + pkg.oneLineNodeDepth(field.Type, depth)
+	return joinStrings(names) + " " + pkg.oneLineNodeDepth(field.Type, depth)
+}
+
+// joinStrings formats the input as a comma-separated list,
+// but truncates the list at some reasonable length if necessary.
+func joinStrings(ss []string) string {
+	var n int
+	for i, s := range ss {
+		n += len(s) + len(", ")
+		if n > punchedCardWidth {
+			ss = append(ss[:i:i], "...")
+			break
+		}
+	}
+	return strings.Join(ss, ", ")
 }
 
 // packageDoc prints the docs for the package (package doc plus one-liners of the rest).
@@ -787,7 +801,6 @@ func (pkg *Package) printMethodDoc(symbol, method string) bool {
 			}
 			name := iMethod.Names[0].Name
 			if match(method, name) {
-				// pkg.oneLineField(iMethod, 0)
 				if iMethod.Doc != nil {
 					for _, comment := range iMethod.Doc.List {
 						doc.ToText(&pkg.buf, comment.Text, "", indent, indentedWidth)

src/cmd/doc/testdata/pkg.go

@@ -173,6 +173,19 @@ const (
 
 const ConstGroup4 ExportedType = ExportedType{}
 
+func newLongLine(ss ...string)
+
+var LongLine = newLongLine(
+	"someArgument1",
+	"someArgument2",
+	"someArgument3",
+	"someArgument4",
+	"someArgument5",
+	"someArgument6",
+	"someArgument7",
+	"someArgument8",
+)
+
 type T2 int
 
 type T1 = T2