From 57a36679c1eb2189a2aaaea4ce18bdd7cda69a2b Mon Sep 17 00:00:00 2001
From: =?utf8?q?David=20=E2=80=98Bombe=E2=80=99=20Roden?=
 <bombe@pterodactylus.net>
Date: Sat, 25 May 2013 14:15:06 +0200
Subject: [PATCH] Add javadoc.

---
 .../net/pterodactylus/sonitus/io/mp3/Frame.java    | 109 ++++++++++++++++++++-
 1 file changed, 108 insertions(+), 1 deletion(-)

diff --git a/src/main/java/net/pterodactylus/sonitus/io/mp3/Frame.java b/src/main/java/net/pterodactylus/sonitus/io/mp3/Frame.java
index ab0c4fd..e6b38e0 100644
--- a/src/main/java/net/pterodactylus/sonitus/io/mp3/Frame.java
+++ b/src/main/java/net/pterodactylus/sonitus/io/mp3/Frame.java
@@ -216,6 +216,34 @@ public class Frame {
 	/** The decoded emphasis mode. */
 	private final int emphasis;
 
+	/**
+	 * Creates a new frame from the given values.
+	 *
+	 * @param mpegAudioVersionId
+	 * 		The MPEG audio version ID
+	 * @param layerDescription
+	 * 		The layer description
+	 * @param protectionBit
+	 * 		The protection bit
+	 * @param bitrateIndex
+	 * 		The bitrate index
+	 * @param samplingRateFrequencyIndex
+	 * 		The sampling rate frequency index
+	 * @param paddingBit
+	 * 		The padding bit
+	 * @param privateBit
+	 * 		The private bit
+	 * @param channelMode
+	 * 		The channel mode
+	 * @param modeExtension
+	 * 		The mode extension
+	 * @param copyrightBit
+	 * 		The copyright bit
+	 * @param originalBit
+	 * 		The original bit
+	 * @param emphasis
+	 * 		The emphasis
+	 */
 	private Frame(int mpegAudioVersionId, int layerDescription, int protectionBit, int bitrateIndex, int samplingRateFrequencyIndex, int paddingBit, int privateBit, int channelMode, int modeExtension, int copyrightBit, int originalBit, int emphasis) {
 		this.mpegAudioVersionId = mpegAudioVersionId;
 		this.layerDescription = layerDescription;
@@ -235,48 +263,103 @@ public class Frame {
 	// ACCESSORS
 	//
 
+	/**
+	 * Returns the MPEG audio version.
+	 *
+	 * @return The MPEG audio version
+	 */
 	public MpegAudioVersion mpegAudioVersion() {
 		return MpegAudioVersion.values()[mpegAudioVersionId];
 	}
 
+	/**
+	 * Returns the layer description.
+	 *
+	 * @return The layer description
+	 */
 	public LayerDescription layerDescription() {
 		return LayerDescription.values()[layerDescription];
 	}
 
+	/**
+	 * Returns the protection bit.
+	 *
+	 * @return {@code true} if the protection bit is set, {@code false} otherwise
+	 */
 	public boolean protectionBit() {
 		return protectionBit != 0;
 	}
 
+	/**
+	 * Returns the bitrate of this frame.
+	 *
+	 * @return The bitrate of this frame (in kbps)
+	 */
 	public int bitrate() {
 		return bitrateSupplier.get().get(mpegAudioVersion()).get(layerDescription()).get(bitrateIndex);
 	}
 
+	/**
+	 * Returns the sampling rate of the audio data in this frame.
+	 *
+	 * @return The sample rate (in Hertz)
+	 */
 	public int samplingRate() {
 		return samplingRateSupplier.get().get(mpegAudioVersion()).get(samplingRateFrequencyIndex);
 	}
 
+	/**
+	 * Returns the padding bit.
+	 *
+	 * @return {@code true} if the padding bit is set, {@code false} otherwise
+	 */
 	public boolean paddingBit() {
 		return paddingBit != 0;
 	}
 
+	/**
+	 * Returns the private bit.
+	 *
+	 * @return {@code true} if the private bit is set, {@code false} otherwise
+	 */
 	public boolean privateBit() {
 		return privateBit != 0;
 	}
 
+	/**
+	 * Returns the channel mode.
+	 *
+	 * @return The channel mode
+	 */
 	public ChannelMode channelMode() {
 		return ChannelMode.values()[channelMode];
 	}
 
 	/* TODO - mode extension. */
 
+	/**
+	 * Returns the copyright bit.
+	 *
+	 * @return {@code true} if the copyright bit is set, {@code false} otherwise
+	 */
 	public boolean copyrightBit() {
 		return copyrightBit != 0;
 	}
 
+	/**
+	 * Returns the original bit.
+	 *
+	 * @return {@code true} if the original bit is set, {@code false} otherwise
+	 */
 	public boolean originalBit() {
 		return originalBit != 0;
 	}
 
+	/**
+	 * Returns the emphasis.
+	 *
+	 * @return The emphasis
+	 */
 	public Emphasis emphasis() {
 		return Emphasis.values()[emphasis];
 	}
@@ -285,10 +368,34 @@ public class Frame {
 	// STATIC METHODS
 	//
 
+	/**
+	 * Returns whether the data beginning at the given offset is an MPEG audio
+	 * frame.
+	 *
+	 * @param buffer
+	 * 		The buffer in which the data is stored
+	 * @param offset
+	 * 		The beginning of the data to parse
+	 * @param length
+	 * 		The length of the data to parse
+	 * @return {@code true} if the data at the given offset is an MPEG audio frame
+	 */
 	public static boolean isFrame(byte[] buffer, int offset, int length) {
-		return (((buffer[offset] & 0xff) == 0xff) && ((buffer[offset + 1] & 0xe0) == 0xe0));
+		return (length > 3) && (((buffer[offset] & 0xff) == 0xff) && ((buffer[offset + 1] & 0xe0) == 0xe0));
 	}
 
+	/**
+	 * Tries to create an MPEG audio from the given data.
+	 *
+	 * @param buffer
+	 * 		The buffer in which the data is stored
+	 * @param offset
+	 * 		The offset at which to look for a frame
+	 * @param length
+	 * 		The length of the data in the buffer
+	 * @return The frame if it could be parsed, or {@link Optional#absent()} if no
+	 *         frame could be found
+	 */
 	public static Optional<Frame> create(byte[] buffer, int offset, int length) {
 		if (isFrame(buffer, offset, length)) {
 			int mpegAudioVersionId = (buffer[offset + 1] & 0x18) >>> 3;
-- 
2.7.4