feat(docs): add @Sample annotation for documentation

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>

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();
+}

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>