Merge pull request #5265 from OfficeDev/main

[Admin] Publish

Author: alison-mk

docs/excel/custom-functions-custom-enums.md

@@ -0,0 +1,119 @@
+---
+title: Custom enums for custom functions
+description: Create custom enums to use with your custom functions.
+ms.date: 06/24/2025
+ms.localizationpriority: medium
+---
+
+# Create custom enums for your custom functions
+
+:::image type="content" source="../images/custom-functions-custom-enum-autocomplete.png" alt-text="The members of a custom enum displaying in the Excel AutoComplete menu.":::
+
+Custom enums give users Excel AutoComplete options for your custom functions. The members in your enum show up in the formula bar as suggestions. The planets in the preceding screenshot are an example of a custom enum that provides a set list. This article describes how to create custom enums and use them as parameters in your custom functions.
+
+## Define the custom enum
+
+Define your enum with the JSDoc tag `@customenum`. The corresponding JSON properties are then autogenerated in your custom function metadata. For more information about JSDoc tags and custom functions, see [Basics of JSDoc tags](custom-functions-json-autogeneration.md#basics-of-jsdoc-tags).
+
+> [!NOTE]
+> Custom enums created with the `@customenum` JSDoc tag are only supported in TypeScript. They are not supported in JavaScript. To use custom enums with JavaScript functions, you must manually create your own JSON metadata. To learn more, see [Manually create JSON metadata](custom-functions-json.md).
+
+The following code snippet shows how to define and use a simple custom enum as a parameter.
+
+```typescript
+/** 
+ * A custom enum with descriptions and tooltips. 
+ * @customenum {string} 
+ */
+enum PLANETS { 
+  /** Mercury is the first planet from the sun. */ 
+  mercury = "Mercury", 
+
+  /** Venus is the second planet from the sun. */ 
+  venus = "Venus", 
+
+  /** Earth is the third planet from the sun. */ 
+  earth = "Earth", 
+} 
+
+/** 
+ * A sample function that uses the custom enum as a parameter.
+ * @customfunction 
+ */ 
+function getPlanets(value: PLANETS): any { 
+  return value; 
+} 
+```
+
+## Use a custom enum multiple times
+
+A custom enum can be reused in multiple functions, and it can be used as multiple parameters of a single function. A function can also have multiple enums as parameters at the same time. An enum parameter can be repeating or optional.
+
+The following code sample shows a `NUMBERS` enum and a custom function that uses the enum multiple times as an input value.
+
+```typescript
+/**
+* Enum of numbers with descriptions and tooltips.
+* @customenum {number}
+*/ 
+enum NUMBERS {
+  /** One */
+  One = 1,
+
+  /** Two */
+  Two = 2,
+
+  /** Three */
+  Three = 3, 
+
+  /** Four */
+  Four = 4,
+
+  /** Five */
+  Five = 5
+} 
+
+/**
+* Enter multiple numbers from the NUMBERS enum and get the sum.
+* @customfunction
+* @param input Enter enum numbers.
+* @returns
+*/
+function addNumbers(input: NUMBERS[]): any {
+  const sum = input.reduce((acc, num) => acc + num, 0); 
+  return "Sum: " + sum; 
+}
+```
+
+## Localize your custom enums
+
+Localizing custom enums is similar to [localizing custom functions](custom-functions-naming.md#localize-custom-functions). You must [manually create your JSON metadata](custom-functions-json.md) and then create a new JSON metadata file for each language.
+
+Note that only the `name` and `tooltip` properties within an enum should be localized to the target language. The `value` property should remain unchanged to avoid the need for handling multiple languages within your function body.
+
+The following JSON snippet shows the Chinese language localized `values` object for the planet Mercury.
+
+```json
+"enums": [
+    {
+        "id": "PLANETS",
+        "type": "string",
+        "values": [
+            {
+                "name": "水星", 
+                "value": "mercury",
+                "tooltip": "水星是距离太阳最近的行星"
+            }
+        ]
+    }
+],
+```
+
+## Backwards compatibility
+
+Custom enums offer backwards compatibility. On older versions of Excel, parameters using a custom enum work as standard parameters without displaying in the Excel AutoComplete list.
+
+## See also
+
+- [Manually create JSON metadata for custom functions](custom-functions-json.md)
+- [Autogenerate JSON metadata for custom functions](custom-functions-json-autogeneration.md)

docs/excel/custom-functions-parameter-options.md

@@ -1,7 +1,7 @@
 ---
 title: Options for Excel custom functions
 description: Learn how to use different parameters within your custom functions, such as Excel ranges, optional parameters, invocation context, and more.
-ms.date: 07/05/2023
+ms.date: 06/26/2025
 ms.localizationpriority: medium
 ---
 
@@ -143,6 +143,9 @@ function secondHighest(values) {
 
 A repeating parameter allows a user to enter a series of optional arguments to a function. When the function is called, the values are provided in an array for the parameter. If the parameter name ends with a number, each argument's number will increase incrementally, such as `ADD(number1, [number2], [number3],…)`. This matches the convention used for built-in Excel functions.
 
+> [!NOTE]
+> For a custom function that takes multiple parameters, a repeating parameter must be the last input parameter in the function. A repeating parameter cannot be followed by another parameter. Similarly, a function can only have one repeating parameter.
+
 The following function sums the total of numbers, cell addresses, as well as ranges, if entered.
 
 ```TS
@@ -173,7 +176,7 @@ This function shows `=CONTOSO.ADD([operands], [operands]...)` in the Excel workb
 
 ### Repeating single value parameter
 
-A repeating single value parameter allows multiple single values to be passed. For example, the user could enter ADD(1,B2,3). The following sample shows how to declare a single value parameter.
+A repeating single value parameter allows multiple single values to be passed. For example, the user could enter **ADD(1,B2,3)**. The following sample shows how to declare a single value parameter.
 
 ```JS
 /**
@@ -192,7 +195,7 @@ function addSingleValue(singleValue) {
 
 ### Single range parameter
 
-A single range parameter isn't technically a repeating parameter, but is included here because the declaration is very similar to repeating parameters. It would appear to the user as ADD(A2:B3) where a single range is passed from Excel. The following sample shows how to declare a single range parameter.
+A single range parameter isn't technically a repeating parameter, but it's included here because the declaration is very similar to repeating parameters. It would appear to the user as **ADD(A2:B3)**, where a single range is passed from Excel. The following sample shows how to declare a single range parameter.
 
 ```JS
 /**
@@ -212,15 +215,13 @@ function addSingleRange(singleRange) {
 
 ### Repeating range parameter
 
-A repeating range parameter allows multiple ranges or numbers to be passed. For example, the user could enter ADD(5,B2,C3,8,E5:E8). Repeating ranges are usually specified with the type `number[][][]` as they are three-dimensional matrices. For a sample, see the main sample listed for [repeating parameters](#repeating-parameters).
-
-### Declaring repeating parameters
+A repeating range parameter allows multiple ranges or numbers to be passed. For example, the user could enter **ADD(5,B2,C3,8,E5:E8)**. Repeating ranges are usually specified with the type `number[][][]` as they are three-dimensional matrices. For a sample, see the main sample listed for [repeating parameters](#repeating-parameters).
 
-In Typescript, indicate that the parameter is multi-dimensional. For example,  `ADD(values: number[])` would indicate a one-dimensional array, `ADD(values:number[][])` would indicate a two-dimensional array, and so on.
+### Declare repeating parameters
 
-In JavaScript, use `@param values {number[]}` for one-dimensional arrays, `@param <name> {number[][]}` for two-dimensional arrays, and so on for more dimensions.
+To declare a repeating parameter, indicate that the parameter is multi-dimensional. For example in TypeScript, `ADD(values: number[])` would indicate a one-dimensional array, `ADD(values:number[][])` would indicate a two-dimensional array, and so on. In JavaScript, use `@param values {number[]}` for one-dimensional arrays, `@param <name> {number[][]}` for two-dimensional arrays, and so on for more dimensions.
 
-For hand-authored JSON, ensure your parameter is specified as ``"repeating"`: true` in your JSON file, as well as check that your parameters are marked as ``"dimensionality"`: matrix`.
+For [manually-created JSON metadata](custom-functions-json.md), ensure that the parameter is specified as `"repeating": true` and `"dimensionality": "matrix"` in your JSON file.
 
 ## Invocation parameter
 

docs/excel/make-custom-functions-compatible-with-xll-udf.md

@@ -24,7 +24,7 @@ The manifest configuration depends on what type of manifest the add-in uses.
 
 # [Unified manifest for Microsoft 365](#tab/jsonmanifest)
 
-The following example shows how to specify both a COM add-in and an XLL add-in as equivalents in a unified manifest. Often you specify both. For completeness, this example shows both equivalents in context. They're identified by their [`"alternates.prefer.comAddin.progId"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-com-addin#progid) and [`"alternates.prefer.xllCustomFunctions.filename"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-xll-custom-functions#filename) respectively. For more information on COM add-in compatibility, see [Make your Office Add-in compatible with an existing COM add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md).
+The following example shows how to specify both a COM add-in and an XLL add-in as equivalents in a unified manifest. Often you specify both. For completeness, this example shows both equivalents in context. They're identified by their [`"alternates.prefer.comAddin.progId"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-com-addin#progid) and `"alternates.prefer.xllCustomFunctions.filename"` respectively. For more information on COM add-in compatibility, see [Make your Office Add-in compatible with an existing COM add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md).
 
 ```json
 "extensions" [

docs/images/custom-functions-custom-enum-autocomplete.png

@@ -677,6 +677,9 @@ items:
     - name: Manually create JSON metadata
       href: excel/custom-functions-json.md
       displayName: Excel, Custom Functions
+    - name: Custom enums
+      href: excel/custom-functions-custom-enums.md
+      displayName: Excel, Custom Functions
     - name: Call Excel JavaScript APIs
       href: excel/call-excel-apis-from-custom-function.md
       displayName: Excel, Custom Functions