Merge "Add comments explaining what those files do."

4 files changed, 36 insertions, 3 deletions

diff --git a/AndroidBoard.mk b/AndroidBoard.mk
index fcdb14a..79207ec 100644
--- a/AndroidBoard.mk
+++ b/AndroidBoard.mk
@@ -12,8 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-LOCAL_PATH := $(call my-dir)
+#
+# AndroidBoard.mk is a legacy mechanism to deal with a few
+# edge-cases that can't be managed otherwise. No new rules
+# should be added to this file.
+#
 
--include vendor/htc/passion/AndroidBoardVendor.mk
+# Least specific includes go first, so that they can get
+# overridden further down
 
+# include rules from the generic passion board
 include device/htc/passion-common/AndroidBoardCommon.mk
+
+# include the non-open-source counterpart to this file
+-include vendor/htc/passion/AndroidBoardVendor.mk
diff --git a/AndroidProducts.mk b/AndroidProducts.mk
index d40692f..bc8dd55 100644
--- a/AndroidProducts.mk
+++ b/AndroidProducts.mk
@@ -12,5 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#
+# This file lists the product definition files that define
+# configurations which are actually buildable (e.g. through lunch)
+#
+
 PRODUCT_MAKEFILES := \
     $(LOCAL_DIR)/generic_passion.mk
diff --git a/BoardConfig.mk b/BoardConfig.mk
index cf921d0..c317658 100644
--- a/BoardConfig.mk
+++ b/BoardConfig.mk
@@ -12,6 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#
+# This file sets variables that control the way modules are built
+# thorughout the system. It should not be used to conditionally
+# disable makefiles (the proper mechanism to control what gets
+# included in a build is to use PRODUCT_PACKAGES in a product
+# definition file).
+#
+
+# Get the generic variables that are common between all versions
+# of passion
 include device/htc/passion-common/BoardConfigCommon.mk
 
 TARGET_RECOVERY_UI_LIB := librecovery_ui_passion librecovery_ui_htc
diff --git a/generic_passion.mk b/generic_passion.mk
index 80625ec..6097ab8 100644
--- a/generic_passion.mk
+++ b/generic_passion.mk
@@ -12,8 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-$(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk)
+#
+# This file is the build configuration for a generic Android
+# build for passion hardware. This cleanly combines a set of
+# device-specific aspects (drivers) with a device-agnostic
+# product configuration (apps).
+#
+
+# Inherit from those products. Most specific first.
 $(call inherit-product, device/htc/passion/passion_us.mk)
+$(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk)
 
+# Discard inherited values and use our own instead.
 PRODUCT_NAME := generic_passion
 PRODUCT_DEVICE := passion