From 288aa52decf6afacf90964f2d3a425c152677fea Mon Sep 17 00:00:00 2001
From: olly <olly@google.com>
Date: Wed, 31 Jul 2019 18:02:21 +0100
Subject: [PATCH] Clean up some Ogg comments & document granulePosition

PiperOrigin-RevId: 260947018
---
 .../extractor/ogg/DefaultOggSeeker.java       | 28 +++++++++----------
 .../extractor/ogg/OggPageHeader.java          | 14 +++++++---
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/DefaultOggSeeker.java b/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/DefaultOggSeeker.java
index c83662ee83..9700760c49 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/DefaultOggSeeker.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/DefaultOggSeeker.java
@@ -147,12 +147,12 @@ import java.io.IOException;
    * which it is sensible to just skip pages to the target granule and pre-roll instead of doing
    * another seek request.
    *
-   * @param targetGranule the target granule position to seek to.
-   * @param input the {@link ExtractorInput} to read from.
-   * @return the position to seek the {@link ExtractorInput} to for a next call or -(currentGranule
+   * @param targetGranule The target granule position to seek to.
+   * @param input The {@link ExtractorInput} to read from.
+   * @return The position to seek the {@link ExtractorInput} to for a next call or -(currentGranule
    *     + 2) if it's close enough to skip to the target page.
-   * @throws IOException thrown if reading from the input fails.
-   * @throws InterruptedException thrown if interrupted while reading from the input.
+   * @throws IOException If reading from the input fails.
+   * @throws InterruptedException If interrupted while reading from the input.
    */
   @VisibleForTesting
   public long getNextSeekPosition(long targetGranule, ExtractorInput input)
@@ -263,8 +263,8 @@ import java.io.IOException;
    * @param input The {@code ExtractorInput} to skip to the next page.
    * @param limit The limit up to which the search should take place.
    * @return Whether the next page was found.
-   * @throws IOException thrown if peeking/reading from the input fails.
-   * @throws InterruptedException thrown if interrupted while peeking/reading from the input.
+   * @throws IOException If peeking/reading from the input fails.
+   * @throws InterruptedException If interrupted while peeking/reading from the input.
    */
   @VisibleForTesting
   boolean skipToNextPage(ExtractorInput input, long limit)
@@ -321,14 +321,14 @@ import java.io.IOException;
    * Skips to the position of the start of the page containing the {@code targetGranule} and returns
    * the granule of the page previous to the target page.
    *
-   * @param input the {@link ExtractorInput} to read from.
-   * @param targetGranule the target granule.
-   * @param currentGranule the current granule or -1 if it's unknown.
-   * @return the granule of the prior page or the {@code currentGranule} if there isn't a prior
+   * @param input The {@link ExtractorInput} to read from.
+   * @param targetGranule The target granule.
+   * @param currentGranule The current granule or -1 if it's unknown.
+   * @return The granule of the prior page or the {@code currentGranule} if there isn't a prior
    *     page.
-   * @throws ParserException thrown if populating the page header fails.
-   * @throws IOException thrown if reading from the input fails.
-   * @throws InterruptedException thrown if interrupted while reading from the input.
+   * @throws ParserException If populating the page header fails.
+   * @throws IOException If reading from the input fails.
+   * @throws InterruptedException If interrupted while reading from the input.
    */
   @VisibleForTesting
   long skipToPageOfGranule(ExtractorInput input, long targetGranule, long currentGranule)
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/OggPageHeader.java b/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/OggPageHeader.java
index ff32ae3462..c7fb3ff6a2 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/OggPageHeader.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/extractor/ogg/OggPageHeader.java
@@ -37,7 +37,13 @@ import java.io.IOException;
 
   public int revision;
   public int type;
+  /**
+   * The absolute granule position of the page. This is the total number of samples from the start
+   * of the file up to the <em>end</em> of the page. Samples partially in the page that continue on
+   * the next page do not count.
+   */
   public long granulePosition;
+
   public long streamSerialNumber;
   public long pageSequenceNumber;
   public long pageChecksum;
@@ -71,10 +77,10 @@ import java.io.IOException;
    * Peeks an Ogg page header and updates this {@link OggPageHeader}.
    *
    * @param input The {@link ExtractorInput} to read from.
-   * @param quiet If {@code true}, no exceptions are thrown but {@code false} is returned if
-   *     something goes wrong.
-   * @return {@code true} if the read was successful. The read fails if the end of the input is
-   *     encountered without reading data.
+   * @param quiet Whether to return {@code false} rather than throwing an exception if the header
+   *     cannot be populated.
+   * @return Whether the read was successful. The read fails if the end of the input is encountered
+   *     without reading data.
    * @throws IOException If reading data fails or the stream is invalid.
    * @throws InterruptedException If the thread is interrupted.
    */