Add missing JavaDoc comments with Example Usage to util package methods

Added JavaDoc with Example Usage sections to non-private methods across 9 files:
- CharSequenceComparator: compare(CharSequence, CharSequence)
- ThrowableUtils: getRootCause(Throwable)
- HierarchicalClassComparator: protected constructor
- ShutdownHookCallbacksThread: class-level doc, constructor, run()
- JarUtils: doFilter(), doExtract()
- ClassPathUtils: resolveClassPaths()
- VersionUtils: currentJavaMajorVersion(), detectJavaMajorVersion()
- ServiceLoaderUtils: loadService(), loadServicesAsList()
- AnnotationUtils: findAttributesMap(Predicate), findAllDeclaredAnnotations

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Copilot

microsphere-java-core/src/main/java/io/microsphere/util/AnnotationUtils.java

@@ -739,12 +739,20 @@ public static List<Annotation> getDeclaredAnnotations(AnnotatedElement annotated
     }
 
     /**
-     * Find all directly declared annotations of the annotated element with filters, not including
-     * meta annotations.
+     * Retrieves all declared annotations from the specified {@link AnnotatedElement}, including those
+     * from its hierarchy, but excluding meta-annotations, applying the given filters.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   List<Annotation> all = AnnotationUtils.findAllDeclaredAnnotations(
+     *       MyClass.class, annotation -> true);
+     *   System.out.println(all); // all declared annotations on MyClass and its superclasses
+     * }</pre>
      *
      * @param annotatedElement    the annotated element
      * @param annotationsToFilter the annotations to filter
      * @return non-null read-only {@link List}
+     * @since 1.0.0
      */
     /**
      * Retrieves all declared annotations from the specified {@link AnnotatedElement}, including those from its hierarchy,
@@ -1220,10 +1228,20 @@ public static Map<String, Object> findAttributesMap(Annotation annotation, Strin
 
     /**
      * Find the attributes map from the specified annotation by the {@link Method attribute method}
+     * filters.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Annotation annotation = ExampleClass.class.getAnnotation(CustomAnnotation.class);
+     *   Map<String, Object> attrs = AnnotationUtils.findAttributesMap(
+     *       annotation, method -> !"toString".equals(method.getName()));
+     *   System.out.println(attrs); // {value=example, count=5}
+     * }</pre>
      *
      * @param annotation         the specified annotation
      * @param attributesToFilter the attribute methods to filter
      * @return non-null read-only {@link Map}
+     * @since 1.0.0
      */
     @Nonnull
     @Immutable

microsphere-java-core/src/main/java/io/microsphere/util/CharSequenceComparator.java

@@ -46,6 +46,23 @@ public class CharSequenceComparator implements Comparator<CharSequence> {
     private CharSequenceComparator() {
     }
 
+    /**
+     * Compares two {@link CharSequence} instances lexicographically.
+     * Null values are considered less than non-null values. Two null values are considered equal.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   int result = CharSequenceComparator.INSTANCE.compare("apple", "banana"); // negative
+     *   int equal = CharSequenceComparator.INSTANCE.compare("same", "same");     // 0
+     *   int nullFirst = CharSequenceComparator.INSTANCE.compare(null, "text");   // negative
+     * }</pre>
+     *
+     * @param c1 the first {@link CharSequence} to compare; may be {@code null}
+     * @param c2 the second {@link CharSequence} to compare; may be {@code null}
+     * @return a negative integer, zero, or a positive integer as {@code c1} is less than,
+     *         equal to, or greater than {@code c2}
+     * @since 1.0.0
+     */
     @Override
     public int compare(CharSequence c1, CharSequence c2) {
         String string1 = toString(c1);

microsphere-java-core/src/main/java/io/microsphere/util/ClassPathUtils.java

@@ -76,6 +76,23 @@ private static Set<String> initClassPaths() {
         return resolveClassPaths(true, runtimeMXBean::getClassPath);
     }
 
+    /**
+     * Resolves class paths from the given supplier if class path is supported.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Set<String> paths = ClassPathUtils.resolveClassPaths(true, () -> "/lib/a.jar:/lib/b.jar");
+     *   // paths contains ["/lib/a.jar", "/lib/b.jar"]
+     *
+     *   Set<String> empty = ClassPathUtils.resolveClassPaths(false, () -> "");
+     *   // empty set returned when not supported
+     * }</pre>
+     *
+     * @param classPathSupported whether the class path is supported
+     * @param classPathSupplier  the supplier providing the class path string
+     * @return a set of resolved class paths, or an empty set if not supported
+     * @since 1.0.0
+     */
     static Set<String> resolveClassPaths(boolean classPathSupported, Supplier<String> classPathSupplier) {
         if (classPathSupported) {
             return resolveClassPaths(classPathSupplier.get());

microsphere-java-core/src/main/java/io/microsphere/util/HierarchicalClassComparator.java

@@ -40,6 +40,20 @@ public class HierarchicalClassComparator implements Comparator<Class<?>> {
      */
     public static final Comparator<Class<?>> DESCENT = ASCENT.reversed();
 
+    /**
+     * Constructs a new {@link HierarchicalClassComparator} instance.
+     * Use the {@link #ASCENT} or {@link #DESCENT} singletons for standard usage.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   // Typically use the provided singletons:
+     *   Comparator<Class<?>> comparator = HierarchicalClassComparator.ASCENT;
+     *   // Or create a subclass:
+     *   HierarchicalClassComparator custom = new HierarchicalClassComparator() {};
+     * }</pre>
+     *
+     * @since 1.0.0
+     */
     protected HierarchicalClassComparator() {
     }
 

microsphere-java-core/src/main/java/io/microsphere/util/ServiceLoaderUtils.java

@@ -555,6 +555,26 @@ public static <S> S loadLastService(Class<S> serviceType, @Nullable ClassLoader
         return loadService(serviceType, classLoader, cached, false);
     }
 
+    /**
+     * Loads a single service implementation, either the first or last, based on the sorted order.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   // Load the first service (used internally by loadFirstService):
+     *   MyService first = ServiceLoaderUtils.loadService(MyService.class, classLoader, false, true);
+     *   // Load the last service (used internally by loadLastService):
+     *   MyService last = ServiceLoaderUtils.loadService(MyService.class, classLoader, false, false);
+     * }</pre>
+     *
+     * @param <S>         the service type
+     * @param serviceType the interface or abstract class representing the service
+     * @param classLoader the class loader to use; may be {@code null}
+     * @param cached      whether to use cached service instances
+     * @param first       {@code true} to return the first service, {@code false} for the last
+     * @return the selected service implementation
+     * @throws IllegalArgumentException if no implementation is found
+     * @since 1.0.0
+     */
     static <S> S loadService(Class<S> serviceType, @Nullable ClassLoader classLoader, boolean cached, boolean first) {
         List<S> serviceList = loadServicesAsList(serviceType, classLoader, cached);
         int index = first ? 0 : serviceList.size() - 1;
@@ -586,6 +606,22 @@ static <S> List<S> loadServicesAsList(Class<S> serviceType, @Nullable ClassLoade
         return serviceList;
     }
 
+    /**
+     * Loads all service implementations as a list using the specified class loader, without caching.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   List<MyService> services = ServiceLoaderUtils.loadServicesAsList(
+     *       MyService.class, Thread.currentThread().getContextClassLoader());
+     * }</pre>
+     *
+     * @param <S>         the service type
+     * @param serviceType the interface or abstract class representing the service
+     * @param classLoader the class loader to use; may be {@code null}
+     * @return a sorted list of service implementations
+     * @throws IllegalArgumentException if no implementation is defined
+     * @since 1.0.0
+     */
     static <S> List<S> loadServicesAsList(Class<S> serviceType, @Nullable ClassLoader classLoader) {
         if (classLoader == null) {
             classLoader = getClassLoader(serviceType);

microsphere-java-core/src/main/java/io/microsphere/util/ShutdownHookCallbacksThread.java

@@ -23,7 +23,15 @@
 import static io.microsphere.util.ShutdownHookUtils.shutdownHookCallbacks;
 
 /**
- * The Thread for executing the {@link Runnable} callbacks
+ * A {@link Thread} that executes registered shutdown hook {@link Runnable} callbacks
+ * when the JVM begins its shutdown sequence.
+ *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // This thread is used internally by ShutdownHookUtils:
+ *   // ShutdownHookUtils.addShutdownHookCallback(() -> System.out.println("Shutting down..."));
+ *   // The ShutdownHookCallbacksThread will execute all registered callbacks on JVM shutdown.
+ * }</pre>
  *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy<a/>
  * @see ShutdownHookUtils#registerShutdownHook()
@@ -38,10 +46,35 @@ class ShutdownHookCallbacksThread extends Thread {
      */
     static final ShutdownHookCallbacksThread INSTANCE = new ShutdownHookCallbacksThread();
 
+    /**
+     * Constructs a new {@link ShutdownHookCallbacksThread} with a default thread name
+     * derived from the class simple name.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   // Internally constructed as a singleton:
+     *   // ShutdownHookCallbacksThread thread = new ShutdownHookCallbacksThread();
+     *   // thread.getName(); // "ShutdownHookCallbacksThread"
+     * }</pre>
+     *
+     * @since 1.0.0
+     */
     ShutdownHookCallbacksThread() {
         setName(getClass().getSimpleName());
     }
 
+    /**
+     * Executes all registered shutdown hook callbacks and then clears the callback registry.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   // This method is invoked automatically by the JVM during shutdown:
+     *   // Runtime.getRuntime().addShutdownHook(ShutdownHookCallbacksThread.INSTANCE);
+     *   // All registered callbacks in ShutdownHookUtils.shutdownHookCallbacks will be executed.
+     * }</pre>
+     *
+     * @since 1.0.0
+     */
     @Override
     public void run() {
         executeShutdownHookCallbacks();

microsphere-java-core/src/main/java/io/microsphere/util/ThrowableUtils.java

@@ -26,6 +26,22 @@
  */
 public abstract class ThrowableUtils implements Utils {
 
+    /**
+     * Retrieves the root cause of the given {@link Throwable} by traversing the cause chain
+     * until a throwable with no cause is found.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Exception root = new IllegalArgumentException("root");
+     *   Exception wrapped = new RuntimeException("wrapped", root);
+     *   Throwable result = ThrowableUtils.getRootCause(wrapped);
+     *   System.out.println(result.getMessage()); // "root"
+     * }</pre>
+     *
+     * @param throwable the throwable whose root cause is to be determined; must not be {@code null}
+     * @return the root cause of the throwable chain
+     * @since 1.0.0
+     */
     public static Throwable getRootCause(Throwable throwable) {
         Throwable rootCause = throwable;
         while (rootCause.getCause() != null) {

microsphere-java-core/src/main/java/io/microsphere/util/VersionUtils.java

@@ -252,10 +252,37 @@ public static boolean testVersion(Version baseVersion, Version.Operator versionO
         return versionOperator.test(baseVersion, comparedVersion);
     }
 
+    /**
+     * Returns the major version string of the currently running Java runtime.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   String majorVersion = VersionUtils.currentJavaMajorVersion();
+     *   System.out.println(majorVersion); // e.g., "17" or "8"
+     * }</pre>
+     *
+     * @return the major version string of the current Java runtime
+     * @since 1.0.0
+     */
     static String currentJavaMajorVersion() {
         return detectJavaMajorVersion(JAVA_VERSION);
     }
 
+    /**
+     * Detects and returns the major version from a Java version string.
+     * Handles both legacy format (e.g., "1.8.0_292") and modern format (e.g., "17.0.1").
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   String major1 = VersionUtils.detectJavaMajorVersion("1.8.0_292"); // "8"
+     *   String major2 = VersionUtils.detectJavaMajorVersion("17.0.1");    // "17"
+     *   String major3 = VersionUtils.detectJavaMajorVersion("21");        // "21"
+     * }</pre>
+     *
+     * @param javaVersion the full Java version string
+     * @return the major version component of the Java version string
+     * @since 1.0.0
+     */
     static String detectJavaMajorVersion(String javaVersion) {
         int firstDotIndex = javaVersion.indexOf(DOT_CHAR);
         if (firstDotIndex > -1) {

microsphere-java-core/src/main/java/io/microsphere/util/jar/JarUtils.java

@@ -196,6 +196,21 @@ public static List<JarEntry> filter(JarFile jarFile, JarEntryFilter jarEntryFilt
         return doFilter(jarEntriesList, jarEntryFilter);
     }
 
+    /**
+     * Filters the given iterable of {@link JarEntry} instances using the specified {@link JarEntryFilter}.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   List<JarEntry> entries = // ... obtain jar entries
+     *   JarEntryFilter filter = entry -> entry.getName().endsWith(".xml");
+     *   List<JarEntry> filtered = JarUtils.doFilter(entries, filter);
+     * }</pre>
+     *
+     * @param jarEntries     the iterable of JAR entries to filter; must not be {@code null}
+     * @param jarEntryFilter the filter to apply; if {@code null}, all entries are included
+     * @return a non-null, read-only list of filtered JAR entries
+     * @since 1.0.0
+     */
     @Nonnull
     @Immutable
     protected static List<JarEntry> doFilter(Iterable<JarEntry> jarEntries, JarEntryFilter jarEntryFilter) {
@@ -414,6 +429,24 @@ public static boolean isDirectoryEntry(URL url) {
         return false;
     }
 
+    /**
+     * Extracts the specified JAR entries from the given {@link JarFile} into the target directory,
+     * preserving the original directory structure.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JarFile jarFile = new JarFile("example.jar");
+     *   List<JarEntry> entries = JarUtils.filter(jarFile, entry -> entry.getName().endsWith(".class"));
+     *   File outputDir = new File("/path/to/output");
+     *   JarUtils.doExtract(jarFile, entries, outputDir);
+     * }</pre>
+     *
+     * @param jarFile         the source JAR file; if {@code null}, no extraction is performed
+     * @param jarEntries      the collection of entries to extract; if empty or {@code null}, no extraction is performed
+     * @param targetDirectory the target directory for extraction; must not be {@code null}
+     * @throws IOException if an I/O error occurs during extraction
+     * @since 1.0.0
+     */
     protected static void doExtract(JarFile jarFile, Collection<JarEntry> jarEntries, File targetDirectory) throws IOException {
         if (jarFile == null || isEmpty(jarEntries)) {
             return;