(pulsar) branch master updated: [fix][test] Fixed Nondeterministic Ordering in Generated Docs Topics (#24973)

[lhotari]

This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git


The following commit(s) were added to refs/heads/master by this push:
     new 560ed266101 [fix][test] Fixed Nondeterministic Ordering in Generated 
Docs Topics (#24973)
560ed266101 is described below

commit 560ed2661019d813d9be16cbaa4e10b0f803d4b4
Author: Lucas Eby <90928360+lucas...@users.noreply.github.com>
AuthorDate: Tue Nov 11 09:17:34 2025 -0600

    [fix][test] Fixed Nondeterministic Ordering in Generated Docs Topics 
(#24973)
---
 .../apache/pulsar/docs/tools/CmdGenerateDocs.java  | 25 ++++++++++++++++++++--
 .../pulsar/docs/tools/CmdGenerateDocsTest.java     |  4 ++--
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git 
a/pulsar-docs-tools/src/main/java/org/apache/pulsar/docs/tools/CmdGenerateDocs.java
 
b/pulsar-docs-tools/src/main/java/org/apache/pulsar/docs/tools/CmdGenerateDocs.java
index a66da9fd6c6..b024ffa8338 100644
--- 
a/pulsar-docs-tools/src/main/java/org/apache/pulsar/docs/tools/CmdGenerateDocs.java
+++ 
b/pulsar-docs-tools/src/main/java/org/apache/pulsar/docs/tools/CmdGenerateDocs.java
@@ -108,7 +108,7 @@ public class CmdGenerateDocs implements Callable<Integer> {
                     sb.append("```shell\n$ ");
                     sb.append(this.commander.getCommandName()).append(" ");
                     sb.append(module).append(" ").append(subK).append(" 
options").append("\n```\n\n");
-                    List<ArgSpec> argSpecs = subV.getCommandSpec().args();
+                    List<ArgSpec> argSpecs = 
getSortedArgs(subV.getCommandSpec().args());
                     if (argSpecs.size() > 0) {
                         sb.append("|Flag|Description|Default|\n");
                         sb.append("|---|---|---|\n");
@@ -128,7 +128,7 @@ public class CmdGenerateDocs implements Callable<Integer> {
             sb.append(" options").append("\n```").append("\n\n");
             sb.append("|Flag|Description|Default|\n");
             sb.append("|---|---|---|\n");
-            List<ArgSpec> argSpecs = commander.getCommandSpec().args();
+            List<ArgSpec> argSpecs = 
getSortedArgs(commander.getCommandSpec().args());
             argSpecs.forEach(option -> {
                 if (option.hidden() || !(option instanceof OptionSpec)) {
                     return;
@@ -144,6 +144,27 @@ public class CmdGenerateDocs implements Callable<Integer> {
         return sb.toString();
     }
 
+    /**
+     * Returns a sorted copy of the argument specifications list, ordered by 
the
+     * OptionSpec order attribute for option specs. Non-option arguments
+     * retain their relative ordering.
+     *
+     * @param args the list of argument specifications to sort
+     * @return a new sorted list
+     */
+    private List<ArgSpec> getSortedArgs(List<ArgSpec> args) {
+        List<ArgSpec> sorted = new ArrayList<>(args);
+        sorted.sort((a, b) -> {
+            if (a instanceof OptionSpec && b instanceof OptionSpec) {
+                OptionSpec optA = (OptionSpec) a;
+                OptionSpec optB = (OptionSpec) b;
+                return Integer.compare(optA.order(), optB.order());
+            }
+            return 0;
+        });
+        return sorted;
+    }
+
     @Override
     public Integer call() throws Exception {
         if (commandNames.size() == 0) {
diff --git 
a/pulsar-docs-tools/src/test/java/org/apache/pulsar/docs/tools/CmdGenerateDocsTest.java
 
b/pulsar-docs-tools/src/test/java/org/apache/pulsar/docs/tools/CmdGenerateDocsTest.java
index 0f0f96f80ec..07101ac384b 100644
--- 
a/pulsar-docs-tools/src/test/java/org/apache/pulsar/docs/tools/CmdGenerateDocsTest.java
+++ 
b/pulsar-docs-tools/src/test/java/org/apache/pulsar/docs/tools/CmdGenerateDocsTest.java
@@ -29,10 +29,10 @@ public class CmdGenerateDocsTest {
 
     @Command
     public class Arguments {
-        @Option(names = {"-h", "--help"}, description = "Show this help 
message")
+        @Option(names = {"-h", "--help"}, description = "Show this help 
message", order = 0)
         private boolean help = false;
 
-        @Option(names = {"-n", "--name"}, description = "Name")
+        @Option(names = {"-n", "--name"}, description = "Name", order = 1)
         private String name;
     }