diff --git a/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/Content.java b/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/Content.java
index 897f64516b6f..97ba72526842 100644
--- a/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/Content.java
+++ b/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/Content.java
@@ -73,7 +73,7 @@ private Content()
      * @param source the source to copy from
      * @param sink the sink to copy to
      * @param callback the callback to notify when the copy is complete
-     * @see #copy(Source, Sink, Chunk.Processor, Callback) to allow processing of individual {@link Chunk}s, including
+     * @see #copy(Source, Sink, Chunk.Processor, Callback) to allow processing of individual {@code Content.Chunk}s, including
      *      the ability to ignore transient failures.
      */
     public static void copy(Source source, Sink sink, Callback callback)
diff --git a/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/CyclicTimeouts.java b/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/CyclicTimeouts.java
index ef7efecaec89..716188d93476 100644
--- a/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/CyclicTimeouts.java
+++ b/jetty-core/jetty-io/src/main/java/org/eclipse/jetty/io/CyclicTimeouts.java
@@ -132,8 +132,11 @@ private void onTimeoutExpired()
     }
 
     /**
-     * <p>Manages the timeout of a new entity.</p>
-     *
+     * <p>Schedules a timeout for a new or modified item.</p>
+     * <p>If an item returned by the {@link #iterator()} has been modified or added so that it may
+     * now be the earliest expiring item, then this method should be called to schedule the timeout.  This need not be called
+     * for a recurrent timeout during {@code Expirable#onTimeoutExpired()}, nor if the timeout of an existing item is increased.
+     * However, it is safe and inexpensive to always call this when modifying an items expiry.</p>
      * @param expirable the new entity to manage the timeout for
      */
     public void schedule(T expirable)