diff --git a/ionic/platform/battery/battery.ts b/ionic/platform/battery/battery.ts
index a20622c44d..b742969466 100644
--- a/ionic/platform/battery/battery.ts
+++ b/ionic/platform/battery/battery.ts
@@ -2,6 +2,18 @@ import * as util from 'ionic/util';
 
 import {NativePlugin} from '../plugin';
 
+/**
+ * Track battery status. Uses the HTMl5 Battery API if available or
+ * the `cordova-plugin-battery-status` plugin.
+ *
+ * @usage
+ *
+ * ```js
+ * Battery.getStatus().then((data) => {
+ *   console.log(data.charging, data.level, data.chargingTime, data.dischargingTime)
+ * });
+ * ```
+ */
 @NativePlugin({
   name: 'Battery',
   platforms: ['ios', 'android', 'web'],
@@ -10,6 +22,15 @@ import {NativePlugin} from '../plugin';
   }
 })
 export class Battery {
+
+  /**
+   * Get the status of the battery. Data is of the format:
+   * { charging, level, chargingTime, dischargingTime }
+   *
+   * Note: certain fields might not be available depending on the platform.
+   *
+   * @return {object} battery status
+   */
   static getStatus() {
     return new Promise((resolve, reject) => {
       if(navigator.getBattery) {