diff --git a/include/hardware/activity_recognition.h b/include/hardware/activity_recognition.h
index 3d3c1bdd..ecac856f 100644
--- a/include/hardware/activity_recognition.h
+++ b/include/hardware/activity_recognition.h
@@ -103,6 +103,12 @@ typedef struct activity_event {
 } activity_event_t;
 
 typedef struct activity_recognition_module {
+    /**
+     * Common methods of the activity recognition module.  This *must* be the first member of
+     * activity_recognition_module as users of this structure will cast a hw_module_t to
+     * activity_recognition_module pointer in contexts where it's known the hw_module_t
+     * references an activity_recognition_module.
+     */
     hw_module_t common;
 
     /*
@@ -126,6 +132,12 @@ typedef struct activity_recognition_callback_procs {
 } activity_recognition_callback_procs_t;
 
 typedef struct activity_recognition_device {
+    /**
+     * Common methods of the activity recognition device.  This *must* be the first member of
+     * activity_recognition_device as users of this structure will cast a hw_device_t to
+     * activity_recognition_device pointer in contexts where it's known the hw_device_t
+     * references an activity_recognition_device.
+     */
     hw_device_t common;
 
     /*
diff --git a/include/hardware/audio.h b/include/hardware/audio.h
index b53cbff1..6c28def0 100644
--- a/include/hardware/audio.h
+++ b/include/hardware/audio.h
@@ -260,6 +260,11 @@ typedef enum {
  */
 
 struct audio_stream_out {
+    /**
+     * Common methods of the audio stream out.  This *must* be the first member of audio_stream_out
+     * as users of this structure will cast a audio_stream to audio_stream_out pointer in contexts
+     * where it's known the audio_stream references an audio_stream_out.
+     */
     struct audio_stream common;
 
     /**
@@ -383,6 +388,11 @@ struct audio_stream_out {
 typedef struct audio_stream_out audio_stream_out_t;
 
 struct audio_stream_in {
+    /**
+     * Common methods of the audio stream in.  This *must* be the first member of audio_stream_in
+     * as users of this structure will cast a audio_stream to audio_stream_in pointer in contexts
+     * where it's known the audio_stream references an audio_stream_in.
+     */
     struct audio_stream common;
 
     /** set the input gain for the audio driver. This method is for
@@ -439,6 +449,11 @@ struct audio_module {
 };
 
 struct audio_hw_device {
+    /**
+     * Common methods of the audio device.  This *must* be the first member of audio_hw_device
+     * as users of this structure will cast a hw_device_t to audio_hw_device pointer in contexts
+     * where it's known the hw_device_t references an audio_hw_device.
+     */
     struct hw_device_t common;
 
     /**
diff --git a/include/hardware/audio_policy.h b/include/hardware/audio_policy.h
index cbaa31d7..0e88361b 100644
--- a/include/hardware/audio_policy.h
+++ b/include/hardware/audio_policy.h
@@ -423,6 +423,12 @@ typedef struct audio_policy_module {
 } audio_policy_module_t;
 
 struct audio_policy_device {
+    /**
+     * Common methods of the audio policy device.  This *must* be the first member of
+     * audio_policy_device as users of this structure will cast a hw_device_t to
+     * audio_policy_device pointer in contexts where it's known the hw_device_t references an
+     * audio_policy_device.
+     */
     struct hw_device_t common;
 
     int (*create_audio_policy)(const struct audio_policy_device *device,
diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
index 25080222..15b3b193 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -254,6 +254,12 @@ typedef struct camera_module_callbacks {
 } camera_module_callbacks_t;
 
 typedef struct camera_module {
+    /**
+     * Common methods of the camera module.  This *must* be the first member of
+     * camera_module as users of this structure will cast a hw_module_t to
+     * camera_module pointer in contexts where it's known the hw_module_t references a
+     * camera_module.
+     */
     hw_module_t common;
 
     /**
diff --git a/include/hardware/consumerir.h b/include/hardware/consumerir.h
index 5adf6be5..15334c11 100644
--- a/include/hardware/consumerir.h
+++ b/include/hardware/consumerir.h
@@ -32,10 +32,22 @@ typedef struct consumerir_freq_range {
 } consumerir_freq_range_t;
 
 typedef struct consumerir_module {
+    /**
+     * Common methods of the consumer IR module.  This *must* be the first member of
+     * consumerir_module as users of this structure will cast a hw_module_t to
+     * consumerir_module pointer in contexts where it's known the hw_module_t references a
+     * consumerir_module.
+     */
     struct hw_module_t common;
 } consumerir_module_t;
 
 typedef struct consumerir_device {
+    /**
+     * Common methods of the consumer IR device.  This *must* be the first member of
+     * consumerir_device as users of this structure will cast a hw_device_t to
+     * consumerir_device pointer in contexts where it's known the hw_device_t references a
+     * consumerir_device.
+     */
     struct hw_device_t common;
 
     /*
diff --git a/include/hardware/fb.h b/include/hardware/fb.h
index 135e4aa3..9df94165 100644
--- a/include/hardware/fb.h
+++ b/include/hardware/fb.h
@@ -36,6 +36,12 @@ __BEGIN_DECLS
 /*****************************************************************************/
 
 typedef struct framebuffer_device_t {
+    /**
+     * Common methods of the framebuffer device.  This *must* be the first member of
+     * framebuffer_device_t as users of this structure will cast a hw_device_t to
+     * framebuffer_device_t pointer in contexts where it's known the hw_device_t references a
+     * framebuffer_device_t.
+     */
     struct hw_device_t common;
 
     /* flags describing some attributes of the framebuffer */
diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h
index b295ebbc..c1e29efa 100644
--- a/include/hardware/fingerprint.h
+++ b/include/hardware/fingerprint.h
@@ -69,6 +69,12 @@ typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
 
 /* Synchronous operation */
 typedef struct fingerprint_device {
+    /**
+     * Common methods of the fingerprint device.  This *must* be the first member of
+     * fingerprint_device as users of this structure will cast a hw_device_t to
+     * fingerprint_device pointer in contexts where it's known the hw_device_t references a
+     * fingerprint_device.
+     */
     struct hw_device_t common;
 
     /*
@@ -121,6 +127,12 @@ typedef struct fingerprint_device {
 } fingerprint_device_t;
 
 typedef struct fingerprint_module {
+    /**
+     * Common methods of the fingerprint module.  This *must* be the first member of
+     * fingerprint_module as users of this structure will cast a hw_module_t to
+     * fingerprint_module pointer in contexts where it's known the hw_module_t references a
+     * fingerprint_module.
+     */
     struct hw_module_t common;
 } fingerprint_module_t;
 
diff --git a/include/hardware/hdmi_cec.h b/include/hardware/hdmi_cec.h
index f049952d..19061530 100644
--- a/include/hardware/hdmi_cec.h
+++ b/include/hardware/hdmi_cec.h
@@ -211,6 +211,11 @@ typedef struct hdmi_event {
 typedef void (*event_callback_t)(const hdmi_event_t* event, void* arg);
 
 typedef struct hdmi_cec_module {
+    /**
+     * Common methods of the HDMI CEC module.  This *must* be the first member of
+     * hdmi_cec_module as users of this structure will cast a hw_module_t to hdmi_cec_module
+     * pointer in contexts where it's known the hw_module_t references a hdmi_cec_module.
+     */
     struct hw_module_t common;
 } hdmi_module_t;
 
@@ -218,6 +223,11 @@ typedef struct hdmi_cec_module {
  * HDMI-CEC HAL interface definition.
  */
 typedef struct hdmi_cec_device {
+    /**
+     * Common methods of the HDMI CEC device.  This *must* be the first member of
+     * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device
+     * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device.
+     */
     struct hw_device_t common;
 
     /*
diff --git a/include/hardware/hwcomposer.h b/include/hardware/hwcomposer.h
index afb4e99c..049edea5 100644
--- a/include/hardware/hwcomposer.h
+++ b/include/hardware/hwcomposer.h
@@ -471,10 +471,22 @@ typedef struct hwc_procs {
 /*****************************************************************************/
 
 typedef struct hwc_module {
+    /**
+     * Common methods of the hardware composer module.  This *must* be the first member of
+     * hwc_module as users of this structure will cast a hw_module_t to
+     * hwc_module pointer in contexts where it's known the hw_module_t references a
+     * hwc_module.
+     */
     struct hw_module_t common;
 } hwc_module_t;
 
 typedef struct hwc_composer_device_1 {
+    /**
+     * Common methods of the hardware composer device.  This *must* be the first member of
+     * hwc_composer_device_1 as users of this structure will cast a hw_device_t to
+     * hwc_composer_device_1 pointer in contexts where it's known the hw_device_t references a
+     * hwc_composer_device_1.
+     */
     struct hw_device_t common;
 
     /*
diff --git a/include/hardware/keymaster.h b/include/hardware/keymaster.h
index 12158bf0..8c5ff14d 100644
--- a/include/hardware/keymaster.h
+++ b/include/hardware/keymaster.h
@@ -83,6 +83,12 @@ enum {
 };
 
 struct keystore_module {
+    /**
+     * Common methods of the keystore module.  This *must* be the first member of
+     * keystore_module as users of this structure will cast a hw_module_t to
+     * keystore_module pointer in contexts where it's known the hw_module_t references a
+     * keystore_module.
+     */
     hw_module_t common;
 };
 
@@ -166,6 +172,12 @@ typedef struct {
  * The parameters that can be set for a given keymaster implementation.
  */
 struct keymaster_device {
+    /**
+     * Common methods of the keymaster device.  This *must* be the first member of
+     * keymaster_device as users of this structure will cast a hw_device_t to
+     * keymaster_device pointer in contexts where it's known the hw_device_t references a
+     * keymaster_device.
+     */
     struct hw_device_t common;
 
     /**
@@ -282,4 +294,3 @@ static inline int keymaster_close(keymaster_device_t* device)
 __END_DECLS
 
 #endif  // ANDROID_HARDWARE_KEYMASTER_H
-
diff --git a/include/hardware/local_time_hal.h b/include/hardware/local_time_hal.h
index 6b6a317e..946e7997 100644
--- a/include/hardware/local_time_hal.h
+++ b/include/hardware/local_time_hal.h
@@ -55,6 +55,12 @@ struct local_time_module {
 };
 
 struct local_time_hw_device {
+    /**
+     * Common methods of the local time hardware device.  This *must* be the first member of
+     * local_time_hw_device as users of this structure will cast a hw_device_t to
+     * local_time_hw_device pointer in contexts where it's known the hw_device_t references a
+     * local_time_hw_device.
+     */
     struct hw_device_t common;
 
     /**
diff --git a/include/hardware/nfc.h b/include/hardware/nfc.h
index 09523b35..3edfeb69 100644
--- a/include/hardware/nfc.h
+++ b/include/hardware/nfc.h
@@ -210,6 +210,12 @@ static inline int nfc_nci_close(nfc_nci_device_t* dev) {
 #define NFC_PN544_CONTROLLER "pn544"
 
 typedef struct nfc_module_t {
+    /**
+     * Common methods of the NFC NXP PN544 module.  This *must* be the first member of
+     * nfc_module_t as users of this structure will cast a hw_module_t to
+     * nfc_module_t pointer in contexts where it's known the hw_module_t references an
+     * nfc_module_t.
+     */
     struct hw_module_t common;
 } nfc_module_t;
 
@@ -227,6 +233,12 @@ typedef enum {
 } nfc_pn544_linktype;
 
 typedef struct {
+    /**
+     * Common methods of the NFC NXP PN544 device.  This *must* be the first member of
+     * nfc_pn544_device_t as users of this structure will cast a hw_device_t to
+     * nfc_pn544_device_t pointer in contexts where it's known the hw_device_t references an
+     * nfc_pn544_device_t.
+     */
     struct hw_device_t common;
 
     /* The number of EEPROM registers to write */
diff --git a/include/hardware/nfc_tag.h b/include/hardware/nfc_tag.h
index 72028f48..040a07d8 100644
--- a/include/hardware/nfc_tag.h
+++ b/include/hardware/nfc_tag.h
@@ -32,10 +32,22 @@ __BEGIN_DECLS
 #define NFC_TAG_ID "tag"
 
 typedef struct nfc_tag_module_t {
+    /**
+     * Common methods of the NFC tag module.  This *must* be the first member of
+     * nfc_tag_module_t as users of this structure will cast a hw_module_t to
+     * nfc_tag_module_t pointer in contexts where it's known the hw_module_t references a
+     * nfc_tag_module_t.
+     */
     struct hw_module_t common;
 } nfc_tag_module_t;
 
 typedef struct nfc_tag_device {
+    /**
+     * Common methods of the NFC tag device.  This *must* be the first member of
+     * nfc_tag_device_t as users of this structure will cast a hw_device_t to
+     * nfc_tag_device_t pointer in contexts where it's known the hw_device_t references a
+     * nfc_tag_device_t.
+     */
     struct hw_device_t common;
 
     /**
diff --git a/include/hardware/vibrator.h b/include/hardware/vibrator.h
index 795d23eb..92b1fd00 100644
--- a/include/hardware/vibrator.h
+++ b/include/hardware/vibrator.h
@@ -35,7 +35,13 @@ __BEGIN_DECLS
 
 struct vibrator_device;
 typedef struct vibrator_device {
-  struct hw_device_t common;
+    /**
+     * Common methods of the vibrator device.  This *must* be the first member of
+     * vibrator_device as users of this structure will cast a hw_device_t to
+     * vibrator_device pointer in contexts where it's known the hw_device_t references a
+     * vibrator_device.
+     */
+    struct hw_device_t common;
 
     /** Turn on vibrator
      *