explain limitations

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

Author: chrisrueger

biz.aQute.bndlib/src/aQute/bnd/build/Project.java

@@ -3891,8 +3891,45 @@ public List<SubProject> getSubProjects() {
 	 * </ul>
 	 * <p>
 	 * The API-based optimization helps prevent rebuild cascades in dependent
-	 * projects when only internal implementation changes occur.
+	 * projects when only internal implementation changes occur. *
+	 * <h2>Timestamp Preservation Strategy</h2>
+	 * <p>
+	 * To avoid unnecessary cascade rebuilds when only non-API changes occur,
+	 * this implementation preserves the output JAR's timestamp when:
+	 * </p>
+	 * <ul>
+	 * <li>Content digest matches (byte-identical), OR</li>
+	 * <li>API digest matches (exported API unchanged)</li>
+	 * </ul>
+	 * <h3>Mechanism</h3>
+	 * <p>
+	 * The system computes content and API digests <strong>before</strong>
+	 * writing the JAR, compares them against previously stored digests, and if
+	 * a match is found, restores the old timestamp after the JAR is written.
+	 * This prevents downstream projects from seeing a "new" dependency based on
+	 * file timestamp alone.
+	 * </p>
+	 * <h3>Limitations</h3>
+	 * <p>
+	 * This pragmatic approach trades perfect accuracy for simplicity:
+	 * </p>
+	 * <ul>
+	 * <li>Timestamps are preserved by directly setting {@code lastModified()}.
+	 * This works well in most incremental build scenarios but may not perfectly
+	 * reflect semantic changes in all edge cases.</li>
+	 * <li>Attempting to perfectly distinguish between "this JAR actually
+	 * changed" vs. "this build cycle recomputed the same thing" across multiple
+	 * asynchronous build tool invocations is complex and fragile.</li>
+	 * <li><strong>Not recommended for:</strong> highly dynamic build
+	 * environments, complex classpath interdependencies, or scenarios requiring
+	 * perfect timestamp accuracy for external build tools.</li>
+	 * </ul>
+	 * <p>
+	 * In practice, this approach provides substantial benefits by preventing
+	 * most unnecessary rebuilds while maintaining reliability.
 	 * </p>
+	 *
+	 * @see RebuildTriggerPolicy#doRebuildTriggerPolicy(Workspace, Jar, File)
 	 */
 	static class RebuildTriggerPolicy {