Merge "Switch "UTC time" to "Unix epoch time" (Location)"

location/java/android/location/GnssClock.java

@@ -23,9 +23,9 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * A class containing a GPS clock timestamp.
+ * A class containing a GNSS clock timestamp.
  *
- * <p>It represents a measurement of the GPS receiver's clock.
+ * <p>It represents a measurement of the GNSS receiver's clock.
  */
 public final class GnssClock implements Parcelable {
     // The following enumerations must be in sync with the values declared in gps.h

location/java/android/location/Location.java

@@ -45,8 +45,8 @@ import java.util.StringTokenizer;
  * timestamp, accuracy, and other information such as bearing, altitude and velocity.
  *
  * <p>All locations generated through {@link LocationManager} are guaranteed to have a valid
- * latitude, longitude, timestamp (both UTC time and elapsed real-time since boot), and accuracy.
- * All other parameters are optional.
+ * latitude, longitude, timestamp (both Unix epoch time and elapsed realtime since boot), and
+ * accuracy. All other parameters are optional.
  */
 public class Location implements Parcelable {
 
@@ -240,36 +240,39 @@ public class Location implements Parcelable {
     }
 
     /**
-     * Return the UTC time of this location fix, in milliseconds since epoch (January 1, 1970).
+     * Returns the Unix epoch time of this location fix, in milliseconds since the start of the Unix
+     * epoch (00:00:00 January 1, 1970 UTC).
      *
      * <p>There is no guarantee that different locations have times set from the same clock.
      * Locations derived from the {@link LocationManager#GPS_PROVIDER} are guaranteed to have their
-     * time set from the clock in use by the satellite constellation that provided the fix.
+     * time originate from the clock in use by the satellite constellation that provided the fix.
      * Locations derived from other providers may use any clock to set their time, though it is most
-     * common to use the device clock (which may be incorrect).
+     * common to use the device's Unix epoch time system clock (which may be incorrect).
      *
-     * <p>Note that the device clock UTC time is not monotonic; it can jump forwards or backwards
-     * unpredictably and may be changed at any time by the user, so this time should not be used to
-     * order or compare locations. Prefer {@link #getElapsedRealtimeNanos} for that purpose, as this
-     * clock is guaranteed to be monotonic.
+     * <p>Note that the device's Unix epoch time system clock is not monotonic; it can jump forwards
+     * or backwards unpredictably and may be changed at any time by the user, so this time should
+     * not be used to order or compare locations. Prefer {@link #getElapsedRealtimeNanos} for that
+     * purpose, as the elapsed realtime clock is guaranteed to be monotonic.
      *
      * <p>On the other hand, this method may be useful for presenting a human readable time to the
      * user, or as a heuristic for comparing location fixes across reboot or across devices.
      *
-     * <p>All locations generated by the {@link LocationManager} are guaranteed to have a UTC time
-     * set, however remember that the device clock may have changed since the location was
+     * <p>All locations generated by the {@link LocationManager} are guaranteed to have this time
+     * set, however remember that the device's system clock may have changed since the location was
      * generated.
      *
-     * @return UTC time of this location
+     * @return the Unix epoch time of this location
      */
     public @IntRange long getTime() {
         return mTimeMs;
     }
 
     /**
-     * Set the UTC time of this location, in milliseconds since epoch (January 1, 1970).
+     * Sets the Unix epoch time of this location fix, in milliseconds since the start of the Unix
+     * epoch (00:00:00 January 1, 1970 UTC).
      *
-     * @param timeMs UTC time of this location
+     * @param timeMs the Unix epoch time of this location
+     * @see #getTime for more information about times / clocks
      */
     public void setTime(@IntRange long timeMs) {
         mTimeMs = timeMs;

location/java/android/location/OnNmeaMessageListener.java

@@ -31,9 +31,8 @@ public interface OnNmeaMessageListener {
     /**
      * Called when an NMEA message is received.
      * @param message NMEA message
-     * @param timestamp Date and time of the location fix, as reported by the GNSS
-     *                  chipset. The value is specified in milliseconds since 0:00
-     *                  UTC 1 January 1970.
+     * @param timestamp Timestamp of the location fix, as reported by the GNSS chipset. The value
+     *                  is specified in Unix time milliseconds since 1st January 1970, 00:00:00 UTC
      */
     void onNmeaMessage(String message, long timestamp);
 }