[Excel] (Custom functions) Add custom enums article (#5252)

* [Excel] (Custom functions) Add custom enums article

* Add JSON, repeating, and localize sections

* Add screenshot, adjust phrasing and samples

* Adjust phrasing

* Copilot feedback

* Apply suggestions from code review

Co-authored-by: Alex Jerabek <[email protected]>

* Move custom enum JSON metadata to another article

* Fix temporarily broken link

* Copilot editor fix

---------

Co-authored-by: Alex Jerabek <[email protected]>

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/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