Improve RuleBuilder documentation and methods

Add a few convenience methods, document all the methods and add
examples that would show up in the godoc if we were to actually
generate it.

Test: rule_builder_test.go
Change-Id: I270fed605ffec34e6f5b36fde0dc9ca52694b741

android/rule_builder.go

@@ -24,31 +24,48 @@ import (
 	"github.com/google/blueprint/proptools"
 )
 
-type RuleBuilderInstall struct {
+// RuleBuilder provides an alternative to ModuleContext.Rule and ModuleContext.Build to add a command line to the build
-	From, To string
+// graph.
-}
-
 type RuleBuilder struct {
 	commands []*RuleBuilderCommand
 	installs []RuleBuilderInstall
 	restat   bool
 }
 
+// NewRuleBuilder returns a newly created RuleBuilder.
+func NewRuleBuilder() *RuleBuilder {
+	return &RuleBuilder{}
+}
+
+// RuleBuilderInstall is a tuple of install from and to locations.
+type RuleBuilderInstall struct {
+	From, To string
+}
+
+// Restat marks the rule as a restat rule, which will be passed to ModuleContext.Rule in BuildParams.Restat.
 func (r *RuleBuilder) Restat() *RuleBuilder {
 	r.restat = true
 	return r
 }
 
+// Install associates an output of the rule with an install location, which can be retrieved later using
+// RuleBuilder.Installs.
 func (r *RuleBuilder) Install(from, to string) {
 	r.installs = append(r.installs, RuleBuilderInstall{from, to})
 }
 
+// Command returns a new RuleBuilderCommand for the rule.  The commands will be ordered in the rule by when they were
+// created by this method.  That can be mutated through their methods in any order, as long as the mutations do not
+// race with any call to Build.
 func (r *RuleBuilder) Command() *RuleBuilderCommand {
 	command := &RuleBuilderCommand{}
 	r.commands = append(r.commands, command)
 	return command
 }
 
+// Inputs returns the list of paths that were passed to the RuleBuilderCommand methods that take input paths, such
+// as RuleBuilderCommand.Input, RuleBuilderComand.Implicit, or RuleBuilderCommand.FlagWithInput.  Inputs to a command
+// that are also outputs of another command in the same RuleBuilder are filtered out.
 func (r *RuleBuilder) Inputs() []string {
 	outputs := r.outputSet()
 
@@ -80,6 +97,8 @@ func (r *RuleBuilder) outputSet() map[string]bool {
 	return outputs
 }
 
+// Outputs returns the list of paths that were passed to the RuleBuilderCommand methods that take output paths, such
+// as RuleBuilderCommand.Output, RuleBuilderCommand.ImplicitOutput, or RuleBuilderCommand.FlagWithInput.
 func (r *RuleBuilder) Outputs() []string {
 	outputs := r.outputSet()
 
@@ -91,10 +110,12 @@ func (r *RuleBuilder) Outputs() []string {
 	return outputList
 }
 
+// Installs returns the list of tuples passed to Install.
 func (r *RuleBuilder) Installs() []RuleBuilderInstall {
 	return append([]RuleBuilderInstall(nil), r.installs...)
 }
 
+// Tools returns the list of paths that were passed to the RuleBuilderCommand.Tool method.
 func (r *RuleBuilder) Tools() []string {
 	var tools []string
 	for _, c := range r.commands {
@@ -103,6 +124,7 @@ func (r *RuleBuilder) Tools() []string {
 	return tools
 }
 
+// Commands returns a slice containing a the built command line for each call to RuleBuilder.Command.
 func (r *RuleBuilder) Commands() []string {
 	var commands []string
 	for _, c := range r.commands {
@@ -111,12 +133,18 @@ func (r *RuleBuilder) Commands() []string {
 	return commands
 }
 
+// BuilderContext is a subset of ModuleContext and SingletonContext.
 type BuilderContext interface {
 	PathContext
 	Rule(PackageContext, string, blueprint.RuleParams, ...string) blueprint.Rule
 	Build(PackageContext, BuildParams)
 }
 
+var _ BuilderContext = ModuleContext(nil)
+var _ BuilderContext = SingletonContext(nil)
+
+// Build adds the built command line to the build graph, with dependencies on Inputs and Tools, and output files for
+// Outputs.
 func (r *RuleBuilder) Build(pctx PackageContext, ctx BuilderContext, name string, desc string) {
 	// TODO: convert RuleBuilder arguments and storage to Paths
 	mctx, _ := ctx.(ModuleContext)
@@ -166,6 +194,10 @@ func (r *RuleBuilder) Build(pctx PackageContext, ctx BuilderContext, name string
 	}
 }
 
+// RuleBuilderCommand is a builder for a command in a command line.  It can be mutated by its methods to add to the
+// command and track dependencies.  The methods mutate the RuleBuilderCommand in place, as well as return the
+// RuleBuilderCommand, so they can be used chained or unchained.  All methods that add text implicitly add a single
+// space as a separator from the previous method.
 type RuleBuilderCommand struct {
 	buf     []byte
 	inputs  []string
@@ -173,6 +205,8 @@ type RuleBuilderCommand struct {
 	tools   []string
 }
 
+// Text adds the specified raw text to the command line.  The text should not contain input or output paths or the
+// rule will not have them listed in its dependencies or outputs.
 func (c *RuleBuilderCommand) Text(text string) *RuleBuilderCommand {
 	if len(c.buf) > 0 {
 		c.buf = append(c.buf, ' ')
@@ -181,67 +215,136 @@ func (c *RuleBuilderCommand) Text(text string) *RuleBuilderCommand {
 	return c
 }
 
+// Textf adds the specified formatted text to the command line.  The text should not contain input or output paths or
+// the rule will not have them listed in its dependencies or outputs.
 func (c *RuleBuilderCommand) Textf(format string, a ...interface{}) *RuleBuilderCommand {
 	return c.Text(fmt.Sprintf(format, a...))
 }
 
+// Flag adds the specified raw text to the command line.  The text should not contain input or output paths or the
+// rule will not have them listed in its dependencies or outputs.
 func (c *RuleBuilderCommand) Flag(flag string) *RuleBuilderCommand {
 	return c.Text(flag)
 }
 
+// FlagWithArg adds the specified flag and argument text to the command line, with no separator between them.  The flag
+// and argument should not contain input or output paths or the rule will not have them listed in its dependencies or
+// outputs.
 func (c *RuleBuilderCommand) FlagWithArg(flag, arg string) *RuleBuilderCommand {
 	return c.Text(flag + arg)
 }
 
+// FlagWithArg adds the specified flag and list of arguments to the command line, with the arguments joined by sep
+// and no separator between the flag and arguments.  The flag and arguments should not contain input or output paths or
+// the rule will not have them listed in its dependencies or outputs.
 func (c *RuleBuilderCommand) FlagWithList(flag string, list []string, sep string) *RuleBuilderCommand {
 	return c.Text(flag + strings.Join(list, sep))
 }
 
+// Tool adds the specified tool path to the command line.  The path will be also added to the dependencies returned by
+// RuleBuilder.Tools.
 func (c *RuleBuilderCommand) Tool(path string) *RuleBuilderCommand {
 	c.tools = append(c.tools, path)
 	return c.Text(path)
 }
 
+// Input adds the specified input path to the command line.  The path will also be added to the dependencies returned by
+// RuleBuilder.Inputs.
 func (c *RuleBuilderCommand) Input(path string) *RuleBuilderCommand {
 	c.inputs = append(c.inputs, path)
 	return c.Text(path)
 }
 
+// Inputs adds the specified input paths to the command line, separated by spaces.  The paths will also be added to the
+// dependencies returned by RuleBuilder.Inputs.
+func (c *RuleBuilderCommand) Inputs(paths []string) *RuleBuilderCommand {
+	for _, path := range paths {
+		c.Input(path)
+	}
+	return c
+}
+
+// Implicit adds the specified input path to the dependencies returned by RuleBuilder.Inputs without modifying the
+// command line.
 func (c *RuleBuilderCommand) Implicit(path string) *RuleBuilderCommand {
 	c.inputs = append(c.inputs, path)
 	return c
 }
 
+// Implicits adds the specified input paths to the dependencies returned by RuleBuilder.Inputs without modifying the
+// command line.
 func (c *RuleBuilderCommand) Implicits(paths []string) *RuleBuilderCommand {
 	c.inputs = append(c.inputs, paths...)
 	return c
 }
 
+// Output adds the specified output path to the command line.  The path will also be added to the outputs returned by
+// RuleBuilder.Outputs.
 func (c *RuleBuilderCommand) Output(path string) *RuleBuilderCommand {
 	c.outputs = append(c.outputs, path)
 	return c.Text(path)
 }
 
+// Outputs adds the specified output paths to the command line, separated by spaces.  The paths will also be added to
+// the outputs returned by RuleBuilder.Outputs.
+func (c *RuleBuilderCommand) Outputs(paths []string) *RuleBuilderCommand {
+	for _, path := range paths {
+		c.Output(path)
+	}
+	return c
+}
+
+// ImplicitOutput adds the specified output path to the dependencies returned by RuleBuilder.Outputs without modifying
+// the command line.
 func (c *RuleBuilderCommand) ImplicitOutput(path string) *RuleBuilderCommand {
 	c.outputs = append(c.outputs, path)
 	return c
 }
 
+// ImplicitOutputs adds the specified output paths to the dependencies returned by RuleBuilder.Outputs without modifying
+// the command line.
+func (c *RuleBuilderCommand) ImplicitOutputs(paths []string) *RuleBuilderCommand {
+	c.outputs = append(c.outputs, paths...)
+	return c
+}
+
+// FlagWithInput adds the specified flag and input path to the command line, with no separator between them.  The path
+// will also be added to the dependencies returned by RuleBuilder.Inputs.
 func (c *RuleBuilderCommand) FlagWithInput(flag, path string) *RuleBuilderCommand {
 	c.inputs = append(c.inputs, path)
 	return c.Text(flag + path)
 }
 
+// FlagWithInputList adds the specified flag and input paths to the command line, with the inputs joined by sep
+// and no separator between the flag and inputs.  The input paths will also be added to the dependencies returned by
+// RuleBuilder.Inputs.
 func (c *RuleBuilderCommand) FlagWithInputList(flag string, paths []string, sep string) *RuleBuilderCommand {
 	c.inputs = append(c.inputs, paths...)
 	return c.FlagWithList(flag, paths, sep)
 }
 
+// FlagForEachInput adds the specified flag joined with each input path to the command line.  The input paths will also
+// be added to the dependencies returned by RuleBuilder.Inputs.  The result is identical to calling FlagWithInput for
+// each input path.
+func (c *RuleBuilderCommand) FlagForEachInput(flag string, paths []string) *RuleBuilderCommand {
+	for _, path := range paths {
+		c.FlagWithInput(flag, path)
+	}
+	return c
+}
+
+// FlagWithOutput adds the specified flag and output path to the command line, with no separator between them.  The path
+// will also be added to the outputs returned by RuleBuilder.Outputs.
 func (c *RuleBuilderCommand) FlagWithOutput(flag, path string) *RuleBuilderCommand {
 	c.outputs = append(c.outputs, path)
 	return c.Text(flag + path)
 }
 
+// String returns the command line.
+func (c *RuleBuilderCommand) String() string {
+	return string(c.buf)
+}
+
 type unknownRulePath struct {
 	path string
 }

android/rule_builder_test.go

@@ -15,15 +15,103 @@
 package android
 
 import (
+	"fmt"
 	"io/ioutil"
 	"os"
 	"path/filepath"
 	"reflect"
+	"strings"
 	"testing"
 )
 
+func ExampleRuleBuilder() {
+	rule := NewRuleBuilder()
+
+	rule.Command().Tool("ld").Inputs([]string{"a.o", "b.o"}).FlagWithOutput("-o ", "linked")
+	rule.Command().Text("echo success")
+
+	// To add the command to the build graph:
+	// rule.Build(pctx, ctx, "link", "link")
+
+	fmt.Printf("commands: %q\n", strings.Join(rule.Commands(), " && "))
+	fmt.Printf("tools: %q\n", rule.Tools())
+	fmt.Printf("inputs: %q\n", rule.Inputs())
+	fmt.Printf("outputs: %q\n", rule.Outputs())
+
+	// Output:
+	// commands: "ld a.o b.o -o linked && echo success"
+	// tools: ["ld"]
+	// inputs: ["a.o" "b.o"]
+	// outputs: ["linked"]
+}
+
+func ExampleRuleBuilderCommand() {
+	rule := NewRuleBuilder()
+
+	// chained
+	rule.Command().Tool("ld").Inputs([]string{"a.o", "b.o"}).FlagWithOutput("-o ", "linked")
+
+	// unchained
+	cmd := rule.Command()
+	cmd.Tool("ld")
+	cmd.Inputs([]string{"a.o", "b.o"})
+	cmd.FlagWithOutput("-o ", "linked")
+
+	// mixed:
+	cmd = rule.Command().Tool("ld")
+	cmd.Inputs([]string{"a.o", "b.o"})
+	cmd.FlagWithOutput("-o ", "linked")
+}
+
+func ExampleRuleBuilderCommand_Flag() {
+	fmt.Println(NewRuleBuilder().Command().
+		Tool("ls").Flag("-l"))
+	// Output:
+	// ls -l
+}
+
+func ExampleRuleBuilderCommand_FlagWithArg() {
+	fmt.Println(NewRuleBuilder().Command().
+		Tool("ls").
+		FlagWithArg("--sort=", "time"))
+	// Output:
+	// ls --sort=time
+}
+
+func ExampleRuleBuilderCommand_FlagForEachInput() {
+	fmt.Println(NewRuleBuilder().Command().
+		Tool("turbine").
+		FlagForEachInput("--classpath ", []string{"a.jar", "b.jar"}))
+	// Output:
+	// turbine --classpath a.jar --classpath b.jar
+}
+
+func ExampleRuleBuilderCommand_FlagWithInputList() {
+	fmt.Println(NewRuleBuilder().Command().
+		Tool("java").
+		FlagWithInputList("-classpath=", []string{"a.jar", "b.jar"}, ":"))
+	// Output:
+	// java -classpath=a.jar:b.jar
+}
+
+func ExampleRuleBuilderCommand_FlagWithInput() {
+	fmt.Println(NewRuleBuilder().Command().
+		Tool("java").
+		FlagWithInput("-classpath=", "a"))
+	// Output:
+	// java -classpath=a
+}
+
+func ExampleRuleBuilderCommand_FlagWithList() {
+	fmt.Println(NewRuleBuilder().Command().
+		Tool("ls").
+		FlagWithList("--sort=", []string{"time", "size"}, ","))
+	// Output:
+	// ls --sort=time,size
+}
+
 func TestRuleBuilder(t *testing.T) {
-	rule := RuleBuilder{}
+	rule := NewRuleBuilder()
 
 	cmd := rule.Command().
 		Flag("Flag").
@@ -112,7 +200,7 @@ func (t *testRuleBuilderSingleton) GenerateBuildActions(ctx SingletonContext) {
 }
 
 func testRuleBuilder_Build(ctx BuilderContext, in Path, out WritablePath) {
-	rule := RuleBuilder{}
+	rule := NewRuleBuilder()
 
 	rule.Command().Tool("cp").Input(in.String()).Output(out.String())
 

dexpreopt/dexpreopt.go

@@ -63,7 +63,7 @@ func GenerateStripRule(global GlobalConfig, module ModuleConfig) (rule *android.
 
 	tools := global.Tools
 
-	rule = &android.RuleBuilder{}
+	rule = android.NewRuleBuilder()
 
 	strip := shouldStripDex(module, global)
 
@@ -95,7 +95,7 @@ func GenerateDexpreoptRule(global GlobalConfig, module ModuleConfig) (rule *andr
 		}
 	}()
 
-	rule = &android.RuleBuilder{}
+	rule = android.NewRuleBuilder()
 
 	generateProfile := module.ProfileClassListing != "" && !global.DisableGenerateProfile