Merge "Improve UX clarity of "limit" query parameter"

codegenerator/common/rust.py

@@ -635,6 +635,34 @@ class RequestParameter(BaseModel):
     setter_name: str | None = None
     setter_type: str | None = None
 
+    def description_with_defaults(self) -> str | None:
+        if (
+            self.location == "query"
+            and self.remote_name == "limit"
+            and not self.description
+        ):
+            return (
+                "Requests a page size of items. Returns a number of items up "
+                "to a limit value. Use the limit parameter to make an initial "
+                "limited request and use the ID of the last-seen item from "
+                "the response as the marker parameter value in a subsequent "
+                "limited request."
+            )
+
+        elif (
+            self.location == "query"
+            and self.remote_name == "marker"
+            and not self.description
+        ):
+            return (
+                "The ID of the last-seen item. Use the limit parameter to "
+                "make an initial limited request and use the ID of the "
+                "last-seen item from the response as the marker parameter "
+                "value in a subsequent limited request."
+            )
+
+        return self.description
+
     @property
     def type_hint(self):
         if not self.is_required and not isinstance(self.data_type, BTreeSet):

codegenerator/rust_cli.py

@@ -293,6 +293,11 @@ class RequestParameter(common_rust.RequestParameter):
         elif self.location == "query":
             macros.update(self.data_type.clap_macros)
             macros.add('help_heading = "Query parameters"')
+            if self.remote_name == "limit":
+                macros.remove("long")
+                macros.add('long("page-size")')
+                macros.add('visible_alias("limit")')
+
         if hasattr(self.data_type, "enum") and self.data_type.enum:
             values = ",".join(f'"{x}"' for x in sorted(self.data_type.enum))
             macros.add(f"value_parser = [{values}]")

codegenerator/templates/rust_cli/path_parameters.j2

@@ -5,7 +5,7 @@ struct PathParameters {
 {%- for param in type_manager.parameters.values() %}
 {%- if param.location == "path" %}
   {%- if not param.resource_link %}
-    {{ macros.docstring(param.description, indent=4) }}
+    {{ macros.docstring(param.description_with_defaults(), indent=4) }}
     {{ param.clap_macros }}
     {{ param.local_name }}: {{ param.type_hint }},
   {%- else %}

codegenerator/templates/rust_cli/query_parameters.j2

@@ -5,7 +5,7 @@ struct QueryParameters {
 {%- for name, param in type_manager.parameters | dictsort %}
 {%- if param.location == "query" %}
   {%- if not param.resource_link %}
-    {{ macros.docstring(param.description, indent=4) }}
+    {{ macros.docstring(param.description_with_defaults(), indent=4) }}
     {{ param.clap_macros }}
     {{ param.local_name}}: {{ param.type_hint }},
   {%- else %}