diff --git a/include/opus.h b/include/opus.h
index 9de31af..abce5c7 100644
--- a/include/opus.h
+++ b/include/opus.h
@@ -525,7 +525,11 @@
   *
   * The repacketizer can be used to merge multiple Opus packets into a single
   * packet or alternatively to split Opus packets that have previously been
-  * merged. The repacketizer currently only operates on elementary Opus
+  * merged. Splitting valid Opus packets is always guaranteed to succeed,
+  * whereas merging valid packets only succeeds if all frames have the same
+  * mode, bandwidth, and frame size, and when the total duration of the merged
+  * packet is no more than 120 ms.
+  * The repacketizer currently only operates on elementary Opus
   * streams. It will not manipualte multistream packets successfully, except in
   * the degenerate case where they consist of data from a single stream.
   *
@@ -581,12 +585,12 @@
   * contain up to <code>TARGET_DURATION_MS</code> milliseconds of data:
   * @code
   * // The maximum number of packets with duration TARGET_DURATION_MS occurs
-  * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*5/2)
+  * // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5)
   * // packets.
-  * unsigned char *data[(TARGET_DURATION_MS*5/2)+1];
-  * opus_int32 len[(TARGET_DURATION_MS*5/2)+1];
+  * unsigned char *data[(TARGET_DURATION_MS*2/5)+1];
+  * opus_int32 len[(TARGET_DURATION_MS*2/5)+1];
   * int nb_packets;
-  * unsigned char out[1277*(TARGET_DURATION_MS*5/2)];
+  * unsigned char out[1277*(TARGET_DURATION_MS*2/2)];
   * opus_int32 out_len;
   * int prev_toc;
   * nb_packets = 0;
@@ -613,8 +617,8 @@
   *   // reference to data[nb_packets][0] should be valid.
   *   if (nb_packets > 0 && (
   *       ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) ||
-  *       opus_packet_get_samples_per_frame(data[nb_packets], 2000)*nb_frames >
-  *       TARGET_DURATION_MS*2))
+  *       opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames >
+  *       TARGET_DURATION_MS*48))
   *   {
   *     out_len = opus_repacketizer_out(rp, out, sizeof(out));
   *     if (out_len < 0)
@@ -648,6 +652,12 @@
   *   output_next_packet(out, out_len);
   * }
   * @endcode
+  *
+  * An alternate way of merging packets is to simply call opus_repacketizer_cat()
+  * unconditionally until it fails. At that point, the merged packet can be
+  * obtained with opus_repacketizer_out() and the input packet for which
+  * opus_repacketizer_cat() needs to be re-added to a newly reinitialized
+  * repacketizer state.
   */
 
 typedef struct OpusRepacketizer OpusRepacketizer;
@@ -658,7 +668,7 @@
 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
 
 /** (Re)initializes a previously allocated repacketizer state.
-  * The state must be the size returned by opus_repacketizer_get_size().
+  * The state must be at least the size returned by opus_repacketizer_get_size().
   * This can be used for applications which use their own allocator instead of
   * malloc().
   * It must also be called to reset the queue of packets waiting to be
@@ -676,7 +686,8 @@
   */
 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
 
-/** Allocates and initializes a repacketizer state.
+/** Allocates memory and initializes the new repacketizer with
+ * opus_repacketizer_init().
   */
 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);