Merge "Add documentation for BuildParams"

android/module.go

@@ -37,26 +37,64 @@ var (
 	DeviceStaticLibrary = "static_library"
 )
 
+// BuildParameters describes the set of potential parameters to build a Ninja rule.
+// In general, these correspond to a Ninja concept.
 type BuildParams struct {
-	Rule            blueprint.Rule
+	// A Ninja Rule that will be written to the Ninja file. This allows factoring out common code
-	Deps            blueprint.Deps
+	// among multiple modules to reduce repetition in the Ninja file of action requirements. A rule
-	Depfile         WritablePath
+	// can contain variables that should be provided in Args.
-	Description     string
+	Rule blueprint.Rule
-	Output          WritablePath
+	// Deps represents the depfile format. When using RuleBuilder, this defaults to GCC when depfiles
-	Outputs         WritablePaths
+	// are used.
-	SymlinkOutput   WritablePath
+	Deps blueprint.Deps
-	SymlinkOutputs  WritablePaths
+	// Depfile is a writeable path that allows correct incremental builds when the inputs have not
-	ImplicitOutput  WritablePath
+	// been fully specified by the Ninja rule. Ninja supports a subset of the Makefile depfile syntax.
+	Depfile WritablePath
+	// A description of the build action.
+	Description string
+	// Output is an output file of the action. When using this field, references to $out in the Ninja
+	// command will refer to this file.
+	Output WritablePath
+	// Outputs is a slice of output file of the action. When using this field, references to $out in
+	// the Ninja command will refer to these files.
+	Outputs WritablePaths
+	// SymlinkOutput is an output file specifically that is a symlink.
+	SymlinkOutput WritablePath
+	// SymlinkOutputs is a slice of output files specifically that is a symlink.
+	SymlinkOutputs WritablePaths
+	// ImplicitOutput is an output file generated by the action. Note: references to `$out` in the
+	// Ninja command will NOT include references to this file.
+	ImplicitOutput WritablePath
+	// ImplicitOutputs is a slice of output files generated by the action. Note: references to `$out`
+	// in the Ninja command will NOT include references to these files.
 	ImplicitOutputs WritablePaths
-	Input           Path
+	// Input is an input file to the Ninja action. When using this field, references to $in in the
-	Inputs          Paths
+	// Ninja command will refer to this file.
-	Implicit        Path
+	Input Path
-	Implicits       Paths
+	// Inputs is a slice of input files to the Ninja action. When using this field, references to $in
-	OrderOnly       Paths
+	// in the Ninja command will refer to these files.
-	Validation      Path
+	Inputs Paths
-	Validations     Paths
+	// Implicit is an input file to the Ninja action. Note: references to `$in` in the Ninja command
-	Default         bool
+	// will NOT include references to this file.
-	Args            map[string]string
+	Implicit Path
+	// Implicits is a slice of input files to the Ninja action. Note: references to `$in` in the Ninja
+	// command will NOT include references to these files.
+	Implicits Paths
+	// OrderOnly are Ninja order-only inputs to the action. When these are out of date, the output is
+	// not rebuilt until they are built, but changes in order-only dependencies alone do not cause the
+	// output to be rebuilt.
+	OrderOnly Paths
+	// Validation is an output path for a validation action. Validation outputs imply lower
+	// non-blocking priority to building non-validation outputs.
+	Validation Path
+	// Validations is a slice of output path for a validation action. Validation outputs imply lower
+	// non-blocking priority to building non-validation outputs.
+	Validations Paths
+	// Whether to skip outputting a default target statement which will be built by Ninja when no
+	// targets are specified on Ninja's command line.
+	Default bool
+	// Args is a key value mapping for replacements of variables within the Rule
+	Args map[string]string
 }
 
 type ModuleBuildParams BuildParams