[docs] add docs for parameterized next link (#2446)

fixes #2445

---------

Co-authored-by: iscai-msft <isabellavcai@gmail.com>

Author: iscai-msft

.chronus/changes/docs-parameterizedNextLink-2025-2-25-17-17-57.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-azure-core"
+---
+
+Add more documentation for parameterized next links

packages/typespec-azure-core/lib/legacy.tsp

@@ -4,6 +4,20 @@ namespace Azure.Core.Legacy;
 
 /**
  * A scalar type representing a next link that requires formatting with parameters to be used.
+ *
+ * @example
+ * ```typespec
+ * model ListCertificateOptions {
+ *   includePending?: string;
+ * }
+ * model Certificate {
+ *   name: string;
+ * }
+ * model Page {
+ *   @items items: Certificate[];
+ *   @nextLink nextLink: Azure.Core.Legacy.parameterizedNextLink<[ListCertificateOptions.includePending]>;
+ * }
+ * ```
  */
 @Azure.Core.Foundations.Private.parameterizedNextLinkConfig(TypeSpec.Reflection.ModelProperty[])
 scalar parameterizedNextLink<ParameterizedParams extends TypeSpec.Reflection.ModelProperty[]>

website/src/content/docs/docs/howtos/Generate client libraries/13pagingOperations.mdx

@@ -287,3 +287,30 @@ NOT_SUPPORTED
 ```
 
 </ClientTabs>
+
+## Advanced
+
+### Parameterized next links (against guidelines)
+
+:::danger
+Parameterized next links are against guidelines. Please don't follow this unless explicitly told to do so
+:::
+
+In very rare cases, there are cases of next links that require parameterization. These cases exist outside of the Azure guidelines for paging, but must be supported for legacy reasons.
+
+In cases like this, you may use the special scalar type `Azure.Core.Legacy.parameterizedNextLink`. You can specify which parameters must be reformatted into the next link. Your emitted SDK will handle the reformatting based on the tsp definition
+
+```tsp
+model ListCertificateOptions {
+  includePending?: string;
+}
+model Certificate {
+  name: string;
+}
+model Page {
+  @items items: Certificate[];
+  @nextLink nextLink: Azure.Core.Legacy.parameterizedNextLink<[
+    ListCertificateOptions.includePending
+  ]>;
+}
+```

website/src/content/docs/docs/libraries/azure-core/reference/data-types.md

@@ -1032,6 +1032,23 @@ A scalar type representing a next link that requires formatting with parameters
 scalar Azure.Core.Legacy.parameterizedNextLink
 ```
 
+#### Examples
+
+```typespec
+model ListCertificateOptions {
+  includePending?: string;
+}
+model Certificate {
+  name: string;
+}
+model Page {
+  @items items: Certificate[];
+  @nextLink nextLink: Azure.Core.Legacy.parameterizedNextLink<[
+    ListCertificateOptions.includePending
+  ]>;
+}
+```
+
 ## Azure.Core.Traits
 
 ### `ListQueryParametersTrait` {#Azure.Core.Traits.ListQueryParametersTrait}