Add scaladoc for StampedFile

main-command/src/main/scala/sbt/Watched.scala

@@ -571,14 +571,36 @@ object WatchConfig {
   }
 }
 
+/**
+ * A File that has a [[Stamp]] value associated with it. In general, the stamp method should be
+ * a cached value that can be read without doing any io. This can be used to improve performance
+ * anywhere where we need to check if files have changed before doing potentially expensive work.
+ */
 trait StampedFile extends File {
   def stamp: Stamp
 }
+
+/**
+ * Provides converter functions from TypedPath to [[StampedFile]].
+ */
 object StampedFile {
+
+  /**
+   * Converts a TypedPath instance to a [[StampedFile]] by calculating the file hash.
+   */
   val sourceConverter: TypedPath => StampedFile =
     new StampedFileImpl(_: TypedPath, forceLastModified = false)
+
+  /**
+   * Converts a TypedPath instance to a [[StampedFile]] using the last modified time.
+   */
   val binaryConverter: TypedPath => StampedFile =
     new StampedFileImpl(_: TypedPath, forceLastModified = true)
+
+  /**
+   * A combined convert that converts TypedPath instances representing *.jar and *.class files
+   * using the last modified time and all other files using the file hash.
+   */
   val converter: TypedPath => StampedFile = (tp: TypedPath) =>
     tp.toPath.toString match {
       case s if s.endsWith(".jar")   => binaryConverter(tp)
@@ -586,6 +608,13 @@ object StampedFile {
       case _                         => sourceConverter(tp)
   }
 
+  /**
+   * Adds a default ordering that just delegates to the java.io.File.compareTo method.
+   */
+  implicit case object ordering extends Ordering[StampedFile] {
+    override def compare(left: StampedFile, right: StampedFile): Int = left.compareTo(right)
+  }
+
   private class StampedFileImpl(typedPath: TypedPath, forceLastModified: Boolean)
       extends java.io.File(typedPath.toPath.toString)
       with StampedFile {