From 51f2b126003d363ac8c97ea2badcee479f025b25 Mon Sep 17 00:00:00 2001
From: Ladislav Thon <lthon@redhat.com>
Date: Wed, 7 Aug 2024 09:17:19 +0200
Subject: [PATCH] Improve javadoc of ClassInfo.fields(), methods() and
 recordComponents()

---
 core/src/main/java/org/jboss/jandex/ClassInfo.java | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/core/src/main/java/org/jboss/jandex/ClassInfo.java b/core/src/main/java/org/jboss/jandex/ClassInfo.java
index ac64cfa0..070e5064 100644
--- a/core/src/main/java/org/jboss/jandex/ClassInfo.java
+++ b/core/src/main/java/org/jboss/jandex/ClassInfo.java
@@ -701,8 +701,10 @@ public final List<AnnotationInstance> classAnnotationsWithRepeatable(DotName nam
      * and static initializer blocks which have the special names of {@code <init>}
      * and {@code <clinit>}, respectively. It does not, however, include inherited methods.
      * These must be discovered by traversing the class hierarchy.
-     * <p>
      * This list may be empty, but is never {@code null}.
+     * <p>
+     * Note that the result <em>doesn't</em> have any guaranteed order. If you need
+     * declaration order, use {@link #unsortedMethods()}.
      *
      * @return the list of methods declared in this class
      */
@@ -832,7 +834,10 @@ public final FieldInfo field(String name) {
     /**
      * Returns a list of all available fields. Only fields declared in this class are available.
      * Locating inherited fields requires traversing the class hierarchy. This list may be
-     * empty, but never null.
+     * empty, but is never {@code null}.
+     * <p>
+     * Note that the result <em>doesn't</em> have any guaranteed order. If you need
+     * declaration order, use {@link #unsortedFields()}.
      *
      * @return a list of fields
      */
@@ -885,9 +890,12 @@ public final RecordComponentInfo recordComponent(String name) {
 
     /**
      * Returns a list of all record components declared by this class.
-     * This list may be empty, but never {@code null}.
+     * This list may be empty, but is never {@code null}.
      * <p>
      * If this class is not a record, returns an empty list.
+     * <p>
+     * Note that the result <em>doesn't</em> have any guaranteed order. If you need
+     * declaration order, use {@link #unsortedRecordComponents()}.
      *
      * @return immutable list of record components
      */