From e4ce619880e831992b005c17dfabb7800994d0c7 Mon Sep 17 00:00:00 2001
From: Jeff Davidson <jpd@google.com>
Date: Fri, 8 Aug 2014 16:48:13 -0700
Subject: [PATCH] Improve documentation of ScanResult and WifiInfo.

Valid dBm ranges should *not* be mentioned in the documentation.
Manufacturers should be able to produce devices which can detect
signal strengths with arbitrary sensitivity rather than being forced
to restrict strengths to a certain range.

Adds a reference to WifiManager.calculateSignalLevel(), an
often-useful method to convert these RSSI values into an absolute
signal level that can be displayed to a user as the signal strength.

Bug: 13731529
Change-Id: I0aae85a6d8bc48ffddd1927d816a1dfbf5230f7e
---
 wifi/java/android/net/wifi/ScanResult.java | 7 +++++--
 wifi/java/android/net/wifi/WifiInfo.java   | 6 +++++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/wifi/java/android/net/wifi/ScanResult.java b/wifi/java/android/net/wifi/ScanResult.java
index a561dc226eabe..a01a6b6b16ab7 100644
--- a/wifi/java/android/net/wifi/ScanResult.java
+++ b/wifi/java/android/net/wifi/ScanResult.java
@@ -18,8 +18,8 @@ package android.net.wifi;
 
 import android.net.wifi.passpoint.WifiPasspointInfo;
 import android.net.wifi.passpoint.WifiPasspointManager;
-import android.os.Parcelable;
 import android.os.Parcel;
+import android.os.Parcelable;
 
 /**
  * Describes information about a detected access point. In addition
@@ -48,7 +48,10 @@ public class ScanResult implements Parcelable {
      */
     public String capabilities;
     /**
-     * The detected signal level in dBm.
+     * The detected signal level in dBm, also known as the RSSI.
+     *
+     * <p>Use {@link android.net.wifi.WifiManager#calculateSignalLevel} to convert this number into
+     * an absolute signal level which can be displayed to a user.
      */
     public int level;
     /**
diff --git a/wifi/java/android/net/wifi/WifiInfo.java b/wifi/java/android/net/wifi/WifiInfo.java
index e8081368dc702..44a71089bb033 100644
--- a/wifi/java/android/net/wifi/WifiInfo.java
+++ b/wifi/java/android/net/wifi/WifiInfo.java
@@ -323,7 +323,11 @@ public class WifiInfo implements Parcelable {
     /**
      * Returns the received signal strength indicator of the current 802.11
      * network, in dBm.
-     * @return the RSSI, in the range -127 to 200
+     *
+     * <p>Use {@link android.net.wifi.WifiManager#calculateSignalLevel} to convert this number into
+     * an absolute signal level which can be displayed to a user.
+     *
+     * @return the RSSI.
      */
     public int getRssi() {
         return mRssi;