From 5953136d9db96c1c9ccf67d13be8a27a4700ca8b Mon Sep 17 00:00:00 2001
From: Peter Chen <peternchen@gmail.com>
Date: Sat, 20 Sep 2025 21:01:12 -0400
Subject: [PATCH] feat(docs): add @Sample annotation for documentation

Marks integration test classes so that markdown pages can be auto generated.
---
 operator-annotations/pom.xml                  | 20 ++++++++++++++
 .../main/java/io/javaoperatorsdk/Sample.java  | 26 +++++++++++++++++++
 pom.xml                                       |  1 +
 3 files changed, 47 insertions(+)
 create mode 100644 operator-annotations/pom.xml
 create mode 100644 operator-annotations/src/main/java/io/javaoperatorsdk/Sample.java

diff --git a/operator-annotations/pom.xml b/operator-annotations/pom.xml
new file mode 100644
index 0000000000..41e94777ce
--- /dev/null
+++ b/operator-annotations/pom.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.javaoperatorsdk</groupId>
+        <artifactId>java-operator-sdk</artifactId>
+        <version>5.1.3-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>operator-annotations</artifactId>
+
+    <properties>
+        <maven.compiler.source>22</maven.compiler.source>
+        <maven.compiler.target>22</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+</project>
\ No newline at end of file
diff --git a/operator-annotations/src/main/java/io/javaoperatorsdk/Sample.java b/operator-annotations/src/main/java/io/javaoperatorsdk/Sample.java
new file mode 100644
index 0000000000..49c6d9bc20
--- /dev/null
+++ b/operator-annotations/src/main/java/io/javaoperatorsdk/Sample.java
@@ -0,0 +1,26 @@
+package io.javaoperatorsdk;
+
+import java.lang.annotation.*;
+
+/**
+ * This annotation marks an integration test class as a sample for the documentation.
+ * Intended for use on test classes only.
+ *
+ * <p><b>Example:</b>
+ * <pre>{@code
+ * @Sample(
+ *  tldr="Usage of PrimaryToSecondaryMapper",
+ *  description="Showcases the usage of PrimaryToSecondaryMapper, in what situation it needs to be used and how to optimize typical uses with Informer indexes."
+ * )
+ * class PrimaryToSecondaryIT {
+ *   // details omitted
+ * }
+ * }</pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+@Documented
+public @interface Sample {
+    String tldr();
+    String description();
+}
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index 2afcd8448a..69524810b7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -36,6 +36,7 @@
     <module>sample-operators</module>
     <module>caffeine-bounded-cache-support</module>
     <module>bootstrapper-maven-plugin</module>
+      <module>operator-annotations</module>
   </modules>
 
   <scm>