Add JavaDoc comments to undocumented non-private methods

Add JavaDoc with Example Usage sections to 9 non-private methods/constructors
across 3 files:

- ShutdownHookUtils: clearShutdownHookCallbacks(), shutdownHookThreadsMap(Class)
- PriorityComparator: compare(Object,Object), compare(Class,Class),
  compare(Class,Class,Class), getValue(Object)
- PropertyResourceBundleControl: no-arg constructor, getFormats(String),
  newBundle(String,Locale,String,ClassLoader,boolean)

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

Author: Copilot

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

@@ -59,15 +59,69 @@ public class PriorityComparator implements Comparator<Object> {
      */
     public static final PriorityComparator INSTANCE = new PriorityComparator();
 
+    /**
+     * Compares two objects based on the value of their {@link javax.annotation.Priority} annotation.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   PriorityComparator comparator = PriorityComparator.INSTANCE;
+     *   int result = comparator.compare(serviceA, serviceB);
+     *   if (result < 0) {
+     *       System.out.println("serviceA has higher priority");
+     *   }
+     * }</pre>
+     *
+     * @param o1 the first object to compare
+     * @param o2 the second object to compare
+     * @return a negative integer, zero, or a positive integer as the first object's priority
+     *         is less than, equal to, or greater than the second object's priority
+     * @since 1.0.0
+     */
     @Override
     public int compare(Object o1, Object o2) {
         return compare(getType(o1), getType(o2));
     }
 
+    /**
+     * Compares two classes based on the value of the default {@link javax.annotation.Priority} annotation.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   int result = PriorityComparator.compare(HighPriorityService.class, LowPriorityService.class);
+     *   System.out.println("Comparison result: " + result);
+     * }</pre>
+     *
+     * @param type1 the first class to compare
+     * @param type2 the second class to compare
+     * @return a negative integer, zero, or a positive integer as the first class's priority
+     *         is less than, equal to, or greater than the second class's priority
+     * @since 1.0.0
+     */
     static int compare(Class<?> type1, Class<?> type2) {
         return compare(type1, type2, PRIORITY_CLASS);
     }
 
+    /**
+     * Compares two classes based on the value of the specified priority annotation.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   int result = PriorityComparator.compare(
+     *       HighPriorityService.class,
+     *       LowPriorityService.class,
+     *       javax.annotation.Priority.class
+     *   );
+     *   System.out.println("Comparison result: " + result);
+     * }</pre>
+     *
+     * @param type1         the first class to compare
+     * @param type2         the second class to compare
+     * @param priorityClass the priority annotation class used to extract priority values
+     * @return a negative integer, zero, or a positive integer as the first class's priority
+     *         is less than, equal to, or greater than the second class's priority;
+     *         returns {@code 0} if the classes are equal or the priority annotation class is {@code null}
+     * @since 1.0.0
+     */
     static int compare(Class<?> type1, Class<?> type2, Class<? extends Annotation> priorityClass) {
         if (Objects.equals(type1, type2) || priorityClass == null) {
             return 0;
@@ -82,6 +136,20 @@ static int compare(Class<?> type1, Class<?> type2, Class<? extends Annotation> p
         return Integer.compare(priorityValue1, priorityValue2);
     }
 
+    /**
+     * Extracts the integer priority value from a priority annotation instance.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Annotation priority = HighPriorityService.class.getAnnotation(javax.annotation.Priority.class);
+     *   int value = PriorityComparator.getValue(priority);
+     *   System.out.println("Priority value: " + value);
+     * }</pre>
+     *
+     * @param priority the priority annotation instance, or {@code null} if not annotated
+     * @return the priority value, or {@code -1} if the annotation is {@code null} or the value is negative
+     * @since 1.0.0
+     */
     static int getValue(Object priority) {
         int value = priority == null ? UNDEFINED_VALUE : invokeMethod(priority, "value");
         return value < 0 ? UNDEFINED_VALUE : value;

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

@@ -75,6 +75,19 @@ public class PropertyResourceBundleControl extends ResourceBundle.Control {
 
     private final String encoding;
 
+    /**
+     * Constructs a {@link PropertyResourceBundleControl} with the default encoding.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   PropertyResourceBundleControl control = new PropertyResourceBundleControl();
+     *   String encoding = control.getEncoding();
+     *   System.out.println("Default encoding: " + encoding);
+     * }</pre>
+     *
+     * @throws UnsupportedCharsetException if the default encoding is not supported
+     * @since 1.0.0
+     */
     protected PropertyResourceBundleControl() throws UnsupportedCharsetException {
         this(DEFAULT_ENCODING);
     }
@@ -89,13 +102,51 @@ protected PropertyResourceBundleControl(final String encoding) throws Unsupporte
         this.encoding = encoding;
     }
 
+    /**
+     * Returns the list of supported formats for the given base name, restricted to properties files only.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   PropertyResourceBundleControl control = PropertyResourceBundleControl.DEFAULT_CONTROL;
+     *   List<String> formats = control.getFormats("my.resources.Messages");
+     *   System.out.println("Supported formats: " + formats);
+     * }</pre>
+     *
+     * @param baseName the base name of the resource bundle
+     * @return a list containing the properties format
+     * @throws NullPointerException if {@code baseName} is {@code null}
+     * @since 1.0.0
+     */
     public final List<String> getFormats(String baseName) {
         if (baseName == null) {
             throw new NullPointerException();
         }
         return FORMAT_PROPERTIES;
     }
 
+    /**
+     * Creates a new {@link ResourceBundle} instance for the given parameters, reading the properties
+     * file with the configured character encoding.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   PropertyResourceBundleControl control = PropertyResourceBundleControl.DEFAULT_CONTROL;
+     *   ResourceBundle bundle = control.newBundle(
+     *       "my.resources.Messages", Locale.US, "java.properties",
+     *       Thread.currentThread().getContextClassLoader(), false
+     *   );
+     *   System.out.println(bundle.getString("greeting"));
+     * }</pre>
+     *
+     * @param baseName    the base name of the resource bundle
+     * @param locale      the locale for which the resource bundle should be loaded
+     * @param format      the resource bundle format to be loaded
+     * @param classLoader the class loader to use for loading the resource
+     * @param reload      whether to bypass the cache and reload the resource
+     * @return a new {@link ResourceBundle} instance, or {@code null} if the resource is not found
+     * @throws IOException if an I/O error occurs while reading the resource
+     * @since 1.0.0
+     */
     public ResourceBundle newBundle(String baseName, Locale locale, String format, final ClassLoader classLoader, final boolean reload) throws IOException {
         String bundleName = super.toBundleName(baseName, locale);
         final String resourceName = super.toResourceName(bundleName, SUFFIX);

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

@@ -372,6 +372,19 @@ public static Queue<Runnable> getShutdownHookCallbacks() {
         return unmodifiableQueue(shutdownHookCallbacks);
     }
 
+    /**
+     * Clears all registered shutdown hook callbacks from the internal queue.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   // Clear all registered shutdown hook callbacks
+     *   ShutdownHookUtils.clearShutdownHookCallbacks();
+     *   Queue<Runnable> callbacks = ShutdownHookUtils.getShutdownHookCallbacks();
+     *   assert callbacks.isEmpty();
+     * }</pre>
+     *
+     * @since 1.0.0
+     */
     static void clearShutdownHookCallbacks() {
         shutdownHookCallbacks.clear();
     }
@@ -382,6 +395,23 @@ private static Map<Thread, Thread> shutdownHookThreadsMap() {
         return shutdownHookThreadsMap(applicationShutdownHooksClass);
     }
 
+    /**
+     * Retrieves the internal map of shutdown hook threads from the specified
+     * {@code java.lang.ApplicationShutdownHooks} class via reflection.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Class<?> clazz = Class.forName("java.lang.ApplicationShutdownHooks");
+     *   Map<Thread, Thread> hooksMap = ShutdownHookUtils.shutdownHookThreadsMap(clazz);
+     *   hooksMap.keySet().forEach(thread ->
+     *       System.out.println("Hook: " + thread.getName())
+     *   );
+     * }</pre>
+     *
+     * @param applicationShutdownHooksClass the {@code java.lang.ApplicationShutdownHooks} class, or {@code null}
+     * @return the map of shutdown hook threads, or an empty map if the class is {@code null}
+     * @since 1.0.0
+     */
     static Map<Thread, Thread> shutdownHookThreadsMap(Class<?> applicationShutdownHooksClass) {
         return applicationShutdownHooksClass == null ? emptyMap() : getStaticFieldValue(applicationShutdownHooksClass, HOOKS_FIELD_NAME);
     }