Improve the documentation in the android/sdk.go file

Makes it adhere to the go standard practice of prefixing documentation
comments with the name of the type/func/method.

Bug: 195754365
Test: m nothing
Change-Id: Idf3fe827edc9b6d67d12a99a4b27539ac938ea95

android/sdk.go

@@ -22,6 +22,8 @@ import (
 	"github.com/google/blueprint/proptools"
 )
 
+// RequiredSdks provides access to the set of SDKs required by an APEX and its contents.
+//
 // Extracted from SdkAware to make it easier to define custom subsets of the
 // SdkAware interface and improve code navigation within the IDE.
 //
@@ -30,11 +32,11 @@ import (
 // is expected to implement RequiredSdks() by reading its own properties like
 // `uses_sdks`.
 type RequiredSdks interface {
-	// The set of SDKs required by an APEX and its contents.
+	// RequiredSdks returns the set of SDKs required by an APEX and its contents.
 	RequiredSdks() SdkRefs
 }
 
-// Provided to improve code navigation with the IDE.
+// sdkAwareWithoutModule is provided simply to improve code navigation with the IDE.
 type sdkAwareWithoutModule interface {
 	RequiredSdks
 
@@ -233,75 +235,85 @@ func IsModuleInVersionedSdk(module Module) bool {
 	return false
 }
 
-// Provide support for generating the build rules which will build the snapshot.
+// SnapshotBuilder provides support for generating the build rules which will build the snapshot.
 type SnapshotBuilder interface {
-	// Copy src to the dest (which is a snapshot relative path) and add the dest
+	// CopyToSnapshot generates a rule that will copy the src to the dest (which is a snapshot
-	// to the zip
+	// relative path) and add the dest to the zip.
 	CopyToSnapshot(src Path, dest string)
 
-	// Return the path to an empty file.
+	// EmptyFile returns the path to an empty file.
 	//
 	// This can be used by sdk member types that need to create an empty file in the snapshot, simply
 	// pass the value returned from this to the CopyToSnapshot() method.
 	EmptyFile() Path
 
-	// Unzip the supplied zip into the snapshot relative directory destDir.
+	// UnzipToSnapshot generates a rule that will unzip the supplied zip into the snapshot relative
+	// directory destDir.
 	UnzipToSnapshot(zipPath Path, destDir string)
 
-	// Add a new prebuilt module to the snapshot. The returned module
+	// AddPrebuiltModule adds a new prebuilt module to the snapshot.
-	// must be populated with the module type specific properties. The following
+	//
-	// properties will be automatically populated.
+	// It is intended to be called from SdkMemberType.AddPrebuiltModule which can add module type
+	// specific properties that are not variant specific. The following properties will be
+	// automatically populated before returning.
 	//
 	// * name
 	// * sdk_member_name
 	// * prefer
 	//
-	// This will result in two Soong modules being generated in the Android. One
+	// Properties that are variant specific will be handled by SdkMemberProperties structure.
-	// that is versioned, coupled to the snapshot version and marked as
+	//
-	// prefer=true. And one that is not versioned, not marked as prefer=true and
+	// Each module created by this method can be output to the generated Android.bp file in two
-	// will only be used if the equivalently named non-prebuilt module is not
+	// different forms, depending on the setting of the SOONG_SDK_SNAPSHOT_VERSION build property.
-	// present.
+	// The two forms are:
+	// 1. A versioned Soong module that is referenced from a corresponding similarly versioned
+	//    snapshot module.
+	// 2. An unversioned Soong module that.
+	//
+	// See sdk/update.go for more information.
 	AddPrebuiltModule(member SdkMember, moduleType string) BpModule
 
-	// The property tag to use when adding a property to a BpModule that contains
+	// SdkMemberReferencePropertyTag returns a property tag to use when adding a property to a
-	// references to other sdk members. Using this will ensure that the reference
+	// BpModule that contains references to other sdk members.
-	// is correctly output for both versioned and unversioned prebuilts in the
-	// snapshot.
 	//
-	// "required: true" means that the property must only contain references
+	// Using this will ensure that the reference is correctly output for both versioned and
-	// to other members of the sdk. Passing a reference to a module that is not a
+	// unversioned prebuilts in the snapshot.
-	// member of the sdk will result in a build error.
 	//
-	// "required: false" means that the property can contain references to modules
+	// "required: true" means that the property must only contain references to other members of the
-	// that are either members or not members of the sdk. If a reference is to a
+	// sdk. Passing a reference to a module that is not a member of the sdk will result in a build
-	// module that is a non member then the reference is left unchanged, i.e. it
+	// error.
-	// is not transformed as references to members are.
 	//
-	// The handling of the member names is dependent on whether it is an internal or
+	// "required: false" means that the property can contain references to modules that are either
-	// exported member. An exported member is one whose name is specified in one of
+	// members or not members of the sdk. If a reference is to a module that is a non member then the
-	// the member type specific properties. An internal member is one that is added
+	// reference is left unchanged, i.e. it is not transformed as references to members are.
-	// due to being a part of an exported (or other internal) member and is not itself
+	//
-	// an exported member.
+	// The handling of the member names is dependent on whether it is an internal or exported member.
+	// An exported member is one whose name is specified in one of the member type specific
+	// properties. An internal member is one that is added due to being a part of an exported (or
+	// other internal) member and is not itself an exported member.
 	//
 	// Member names are handled as follows:
-	// * When creating the unversioned form of the module the name is left unchecked
+	// * When creating the unversioned form of the module the name is left unchecked unless the member
-	//   unless the member is internal in which case it is transformed into an sdk
+	//   is internal in which case it is transformed into an sdk specific name, i.e. by prefixing with
-	//   specific name, i.e. by prefixing with the sdk name.
+	//   the sdk name.
 	//
-	// * When creating the versioned form of the module the name is transformed into
+	// * When creating the versioned form of the module the name is transformed into a versioned sdk
-	//   a versioned sdk specific name, i.e. by prefixing with the sdk name and
+	//   specific name, i.e. by prefixing with the sdk name and suffixing with the version.
-	//   suffixing with the version.
 	//
 	// e.g.
 	// bpPropertySet.AddPropertyWithTag("libs", []string{"member1", "member2"}, builder.SdkMemberReferencePropertyTag(true))
 	SdkMemberReferencePropertyTag(required bool) BpPropertyTag
 }
 
+// BpPropertyTag is a marker interface that can be associated with properties in a BpPropertySet to
+// provide additional information which can be used to customize their behavior.
 type BpPropertyTag interface{}
 
-// A set of properties for use in a .bp file.
+// BpPropertySet is a set of properties for use in a .bp file.
 type BpPropertySet interface {
-	// Add a property, the value can be one of the following types:
+	// AddProperty adds a property.
+	//
+	// The value can be one of the following types:
 	// * string
 	// * array of the above
 	// * bool
@@ -326,18 +338,18 @@ type BpPropertySet interface {
 	// * Otherwise, if a property exists with the name then it is an error.
 	AddProperty(name string, value interface{})
 
-	// Add a property with an associated tag
+	// AddPropertyWithTag adds a property with an associated property tag.
 	AddPropertyWithTag(name string, value interface{}, tag BpPropertyTag)
 
-	// Add a property set with the specified name and return so that additional
+	// AddPropertySet adds a property set with the specified name and returns it so that additional
-	// properties can be added.
+	// properties can be added to it.
 	AddPropertySet(name string) BpPropertySet
 
-	// Add comment for property (or property set).
+	// AddCommentForProperty adds a comment for the named property (or property set).
 	AddCommentForProperty(name, text string)
 }
 
-// A .bp module definition.
+// BpModule represents a module definition in a .bp file.
 type BpModule interface {
 	BpPropertySet
 
@@ -364,13 +376,14 @@ func (b BpPrintableBase) bpPrintable() {
 
 var _ BpPrintable = BpPrintableBase{}
 
-// An individual member of the SDK, includes all of the variants that the SDK
+// SdkMember is an individual member of the SDK.
-// requires.
+//
+// It includes all of the variants that the SDK depends upon.
 type SdkMember interface {
-	// The name of the member.
+	// Name returns the name of the member.
 	Name() string
 
-	// All the variants required by the SDK.
+	// Variants returns all the variants of this module depended upon by the SDK.
 	Variants() []SdkAware
 }
 
@@ -418,8 +431,8 @@ func (t *sdkMemberDependencyTag) ExportMember() bool {
 	return t.export
 }
 
-// Prevent dependencies from the sdk/module_exports onto their members from being
+// ReplaceSourceWithPrebuilt prevents dependencies from the sdk/module_exports onto their members
-// replaced with a preferred prebuilt.
+// from being replaced with a preferred prebuilt.
 func (t *sdkMemberDependencyTag) ReplaceSourceWithPrebuilt() bool {
 	return false
 }
@@ -431,7 +444,7 @@ func DependencyTagForSdkMemberType(memberType SdkMemberType, export bool) SdkMem
 	return &sdkMemberDependencyTag{memberType: memberType, export: export}
 }
 
-// Interface that must be implemented for every type that can be a member of an
+// SdkMemberType is the interface that must be implemented for every type that can be a member of an
 // sdk.
 //
 // The basic implementation should look something like this, where ModuleType is
@@ -452,43 +465,43 @@ func DependencyTagForSdkMemberType(memberType SdkMemberType, export bool) SdkMem
 //    ...methods...
 //
 type SdkMemberType interface {
-	// The name of the member type property on an sdk module.
+	// SdkPropertyName returns the name of the member type property on an sdk module.
 	SdkPropertyName() string
 
 	// RequiresBpProperty returns true if this member type requires its property to be usable within
 	// an Android.bp file.
 	RequiresBpProperty() bool
 
-	// True if the member type supports the sdk/sdk_snapshot, false otherwise.
+	// UsableWithSdkAndSdkSnapshot returns true if the member type supports the sdk/sdk_snapshot,
+	// false otherwise.
 	UsableWithSdkAndSdkSnapshot() bool
 
-	// Return true if prebuilt host artifacts may be specific to the host OS. Only
+	// IsHostOsDependent returns true if prebuilt host artifacts may be specific to the host OS. Only
-	// applicable to modules where HostSupported() is true. If this is true,
+	// applicable to modules where HostSupported() is true. If this is true, snapshots will list each
-	// snapshots will list each host OS variant explicitly and disable all other
+	// host OS variant explicitly and disable all other host OS'es.
-	// host OS'es.
 	IsHostOsDependent() bool
 
-	// Add dependencies from the SDK module to all the module variants the member
+	// AddDependencies adds dependencies from the SDK module to all the module variants the member
-	// type contributes to the SDK. `names` is the list of module names given in
+	// type contributes to the SDK. `names` is the list of module names given in the member type
-	// the member type property (as returned by SdkPropertyName()) in the SDK
+	// property (as returned by SdkPropertyName()) in the SDK module. The exact set of variants
-	// module. The exact set of variants required is determined by the SDK and its
+	// required is determined by the SDK and its properties. The dependencies must be added with the
-	// properties. The dependencies must be added with the supplied tag.
+	// supplied tag.
 	//
 	// The BottomUpMutatorContext provided is for the SDK module.
 	AddDependencies(ctx SdkDependencyContext, dependencyTag blueprint.DependencyTag, names []string)
 
-	// Return true if the supplied module is an instance of this member type.
+	// IsInstance returns true if the supplied module is an instance of this member type.
 	//
-	// This is used to check the type of each variant before added to the
+	// This is used to check the type of each variant before added to the SdkMember. Returning false
-	// SdkMember. Returning false will cause an error to be logged expaining that
+	// will cause an error to be logged explaining that the module is not allowed in whichever sdk
-	// the module is not allowed in whichever sdk property it was added.
+	// property it was added.
 	IsInstance(module Module) bool
 
 	// UsesSourceModuleTypeInSnapshot returns true when the AddPrebuiltModule() method returns a
 	// source module type.
 	UsesSourceModuleTypeInSnapshot() bool
 
-	// Add a prebuilt module that the sdk will populate.
+	// AddPrebuiltModule is called to add a prebuilt module that the sdk will populate.
 	//
 	// The sdk module code generates the snapshot as follows:
 	//
@@ -525,7 +538,8 @@ type SdkMemberType interface {
 	//
 	AddPrebuiltModule(ctx SdkMemberContext, member SdkMember) BpModule
 
-	// Create a structure into which variant specific properties can be added.
+	// CreateVariantPropertiesStruct creates a structure into which variant specific properties can be
+	// added.
 	CreateVariantPropertiesStruct() SdkMemberProperties
 }
 
@@ -535,7 +549,8 @@ type SdkDependencyContext interface {
 	BottomUpMutatorContext
 }
 
-// Base type for SdkMemberType implementations.
+// SdkMemberTypeBase is the base type for SdkMemberType implementations and must be embedded in any
+// struct that implements SdkMemberType.
 type SdkMemberTypeBase struct {
 	PropertyName string
 
@@ -572,7 +587,7 @@ func (b *SdkMemberTypeBase) UsesSourceModuleTypeInSnapshot() bool {
 	return b.UseSourceModuleTypeInSnapshot
 }
 
-// Encapsulates the information about registered SdkMemberTypes.
+// SdkMemberTypesRegistry encapsulates the information about registered SdkMemberTypes.
 type SdkMemberTypesRegistry struct {
 	// The list of types sorted by property name.
 	list []SdkMemberType
@@ -610,14 +625,15 @@ func (r *SdkMemberTypesRegistry) UniqueOnceKey() OnceKey {
 	return NewCustomOnceKey(r)
 }
 
-// The set of registered SdkMemberTypes for module_exports modules.
+// ModuleExportsMemberTypes is the set of registered SdkMemberTypes for module_exports modules.
 var ModuleExportsMemberTypes = &SdkMemberTypesRegistry{}
 
-// The set of registered SdkMemberTypes for sdk modules.
+// SdkMemberTypes is the set of registered SdkMemberTypes for sdk modules.
 var SdkMemberTypes = &SdkMemberTypesRegistry{}
 
-// Register an SdkMemberType object to allow them to be used in the sdk and sdk_snapshot module
+// RegisterSdkMemberType registers an SdkMemberType object to allow them to be used in the
-// types.
+// module_exports, module_exports_snapshot and (depending on the value returned from
+// SdkMemberType.UsableWithSdkAndSdkSnapshot) the sdk and sdk_snapshot module types.
 func RegisterSdkMemberType(memberType SdkMemberType) {
 	// All member types are usable with module_exports.
 	ModuleExportsMemberTypes = ModuleExportsMemberTypes.copyAndAppend(memberType)
@@ -628,7 +644,8 @@ func RegisterSdkMemberType(memberType SdkMemberType) {
 	}
 }
 
-// Base structure for all implementations of SdkMemberProperties.
+// SdkMemberPropertiesBase is the base structure for all implementations of SdkMemberProperties and
+// must be embedded in any struct that implements SdkMemberProperties.
 //
 // Contains common properties that apply across many different member types.
 type SdkMemberPropertiesBase struct {
@@ -655,7 +672,7 @@ type SdkMemberPropertiesBase struct {
 	Compile_multilib string `android:"arch_variant"`
 }
 
-// The os prefix to use for any file paths in the sdk.
+// OsPrefix returns the os prefix to use for any file paths in the sdk.
 //
 // Is an empty string if the member only provides variants for a single os type, otherwise
 // is the OsType.Name.
@@ -671,35 +688,47 @@ func (b *SdkMemberPropertiesBase) Base() *SdkMemberPropertiesBase {
 	return b
 }
 
-// Interface to be implemented on top of a structure that contains variant specific
+// SdkMemberProperties is the interface to be implemented on top of a structure that contains
-// information.
+// variant specific information.
 //
-// Struct fields that are capitalized are examined for common values to extract. Fields
+// Struct fields that are capitalized are examined for common values to extract. Fields that are not
-// that are not capitalized are assumed to be arch specific.
+// capitalized are assumed to be arch specific.
 type SdkMemberProperties interface {
-	// Access the base structure.
+	// Base returns the base structure.
 	Base() *SdkMemberPropertiesBase
 
-	// Populate this structure with information from the variant.
+	// PopulateFromVariant populates this structure with information from a module variant.
+	//
+	// It will typically be called once for each variant of a member module that the SDK depends upon.
 	PopulateFromVariant(ctx SdkMemberContext, variant Module)
 
-	// Add the information from this structure to the property set.
+	// AddToPropertySet adds the information from this structure to the property set.
+	//
+	// This will be called for each instance of this structure on which the PopulateFromVariant method
+	// was called and also on a number of different instances of this structure into which properties
+	// common to one or more variants have been copied. Therefore, implementations of this must handle
+	// the case when this structure is only partially populated.
 	AddToPropertySet(ctx SdkMemberContext, propertySet BpPropertySet)
 }
 
-// Provides access to information common to a specific member.
+// SdkMemberContext provides access to information common to a specific member.
 type SdkMemberContext interface {
 
-	// The module context of the sdk common os variant which is creating the snapshot.
+	// SdkModuleContext returns the module context of the sdk common os variant which is creating the
+	// snapshot.
+	//
+	// This is common to all members of the sdk and is not specific to the member being processed.
+	// If information about the member being processed needs to be obtained from this ModuleContext it
+	// must be obtained using one of the OtherModule... methods not the Module... methods.
 	SdkModuleContext() ModuleContext
 
-	// The builder of the snapshot.
+	// SnapshotBuilder the builder of the snapshot.
 	SnapshotBuilder() SnapshotBuilder
 
-	// The type of the member.
+	// MemberType returns the type of the member currently being processed.
 	MemberType() SdkMemberType
 
-	// The name of the member.
+	// Name returns the name of the member currently being processed.
 	//
 	// Provided for use by sdk members to create a member specific location within the snapshot
 	// into which to copy the prebuilt files.

sdk/update.go

@@ -765,6 +765,8 @@ type propertyTag struct {
 	name string
 }
 
+var _ android.BpPropertyTag = propertyTag{}
+
 // A BpPropertyTag to add to a property that contains references to other sdk members.
 //
 // This will cause the references to be rewritten to a versioned reference in the version