Skip to content

[Excel] (Custom functions) Add new JSDoc tags and metadata reference info #5240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Jul 11, 2025

Conversation

alison-mk
Copy link
Contributor

@alison-mk alison-mk commented Jun 18, 2025

The new custom enums article is added in a separate PR: #5252

Copy link
Contributor

Learn Build status updates of commit 28de69d:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View

For more details, please refer to the build report.

Copy link
Contributor

Learn Build status updates of commit 9ae2248:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-json.md ✅Succeeded View

For more details, please refer to the build report.

Copy link
Contributor

Learn Build status updates of commit a094553:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View

For more details, please refer to the build report.

Copy link
Contributor

Learn Build status updates of commit ecbf5e4:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View

For more details, please refer to the build report.

Copy link
Contributor

Learn Build status updates of commit a1193d3:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View

For more details, please refer to the build report.

@alison-mk alison-mk changed the title [Excel] (Custom functions) Add streaming tags [Excel] (Custom functions) Add new JSDoc tags and metadata reference info Jun 26, 2025
Copy link
Contributor

Learn Build status updates of commit 8d47130:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 173, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit f3b230b:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 186, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.
  • Line 330, Column 222: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit 34f0edf:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 186, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.
  • Line 331, Column 222: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

@alison-mk alison-mk marked this pull request as ready for review June 26, 2025 22:15
Copy link
Contributor

Learn Build status updates of commit 35135cc:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details
docs/excel/custom-functions-troubleshooting.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 186, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.
  • Line 331, Column 196: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-troubleshooting.md

  • Line 121, Column 43: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#associating-function-names-with-json-metadata' in 'excel/custom-functions-json.md', did you mean '#associate-function-names-with-json-metadata'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

@alison-mk alison-mk requested a review from Copilot June 26, 2025 22:30
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR enhances the Excel custom functions documentation by adding support for custom enums in JSON metadata and updating the autogeneration guide with new JSDoc tags.

  • Introduces a GETPLANETS example and an enums section in the JSON metadata docs
  • Updates the options table formatting and heading styles
  • Adds four new JSDoc tags (@capturesCallingObject, @customenum, @excludeFromAutoComplete, @linkedEntityLoadService) in the autogeneration guide

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
docs/excel/custom-functions-json.md Added enum metadata example (GETPLANETS), new enums section, updated options table and headings
docs/excel/custom-functions-json-autogeneration.md Inserted new JSDoc tags for custom enums and other behaviors, updated the supported-tags list
Comments suppressed due to low confidence (4)

docs/excel/custom-functions-json.md:188

  • The enums property table lists only name, tooltip, and value, but omits the required id and type fields. Add rows for id (string, Yes) and type (string, Yes).
| Property      | Data type | Required | Description                                                                                                                                                                      |

docs/excel/custom-functions-json.md:200

  • [nitpick] Data type casing is inconsistent—previous tables use lowercase boolean. Standardize to lowercase (boolean) for consistency across the docs.
| `cancelable`      | Boolean   | No<br/><br/>Default value is `false`.  | If `true`, Excel calls the `CancelableInvocation` handler whenever the user takes an action that has the effect of canceling the function; for example, manually triggering recalculation or editing a cell that is referenced by the function. Cancelable functions are typically only used for asynchronous functions that return a single result and need to handle the cancellation of a request for data. A function can't use both the `stream` and `cancelable` properties. |

docs/excel/custom-functions-json-autogeneration.md:127

  • [nitpick] The @customenum tag is introduced but lacks a usage example. Consider adding a small code snippet showing how to annotate a function with @customenum and its {type} parameter.
<a id="customenum"></a>

docs/excel/custom-functions-json.md:125

  • The functions array closing bracket is missing a trailing comma before the "enums" property, causing invalid JSON. Add a comma after line 124 (]).
  "enums": [ 

Copy link
Contributor

Learn Build status updates of commit 9f399bb:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details
docs/excel/custom-functions-troubleshooting.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 186, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.
  • Line 331, Column 196: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-troubleshooting.md

  • Line 121, Column 43: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#associating-function-names-with-json-metadata' in 'excel/custom-functions-json.md', did you mean '#associate-function-names-with-json-metadata'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit e33bc51:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details
docs/excel/custom-functions-troubleshooting.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 186, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.
  • Line 331, Column 196: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-troubleshooting.md

  • Line 121, Column 43: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#associating-function-names-with-json-metadata' in 'excel/custom-functions-json.md', did you mean '#associate-function-names-with-json-metadata'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit e53207b:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-json-autogeneration.md ⚠️Warning View Details
docs/excel/custom-functions-json.md ⚠️Warning View Details
docs/excel/custom-functions-troubleshooting.md ⚠️Warning View Details

docs/excel/custom-functions-json-autogeneration.md

  • Line 133, Column 85: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-json.md

  • Line 186, Column 71: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.
  • Line 331, Column 196: [Warning: file-not-found - See documentation] Invalid file link: 'custom-functions-custom-enums.md'.

docs/excel/custom-functions-troubleshooting.md

  • Line 121, Column 43: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#associating-function-names-with-json-metadata' in 'excel/custom-functions-json.md', did you mean '#associate-function-names-with-json-metadata'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit 0a6c449:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-troubleshooting.md ⚠️Warning View Details
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View

docs/excel/custom-functions-troubleshooting.md

  • Line 121, Column 43: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#associating-function-names-with-json-metadata' in 'excel/custom-functions-json.md', did you mean '#associate-function-names-with-json-metadata'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit 3e8bbb8:

⚠️ Validation status: warnings

File Status Preview URL Details
docs/excel/custom-functions-troubleshooting.md ⚠️Warning View Details
docs/excel/custom-functions-custom-enums.md ✅Succeeded View
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View

docs/excel/custom-functions-troubleshooting.md

  • Line 121, Column 43: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#associating-function-names-with-json-metadata' in 'excel/custom-functions-json.md', did you mean '#associate-function-names-with-json-metadata'?

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copy link
Contributor

Learn Build status updates of commit c8a0e8b:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-custom-enums.md ✅Succeeded View
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View
docs/excel/custom-functions-troubleshooting.md ✅Succeeded View

For more details, please refer to the build report.

Copy link
Member

@davidchesnut davidchesnut left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, a few comments.

@@ -165,17 +178,35 @@ The `functions` property is an array of custom function objects. The following t
| `parameters` | array | Yes | Array that defines the input parameters for the function. See [parameters](#parameters) for details. |
| `result` | object | Yes | Object that defines the type of information that is returned by the function. See [result](#result) for details. |

### enums

The `enums` property is an array of [enum](https://www.typescriptlang.org/docs/handbook/enums.html) constants. The following table lists the properties of each constant.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the JSON it looks like it is metadata describing enums. It's not an actual array of enums in the JSON.

Copy link
Contributor Author

@alison-mk alison-mk Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the JSON example in this article, there's only one enum (id: PLANETS) in the array. Maybe "array" is wrong term here though, do you think there's a better term or phrasing for this sentence? What I'm trying to communicate is that multiple custom enums can be defined with the enums property.

"enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          ...
        }, 
      ] 
    }, 
    {
    "id": "SECONDENUM", 
      "type": "string", 
      "values": [ 
        { 
          ...
        }, 
      ] 
     }
]

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The enums is an array which could including multiple enum objects, the sample could be:

"enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
         ...
        }, 
      ] 
    }, 
    {
    "id": "DayOfWeek", 
      "type": "number", 
      "values": [ 
        { 
            "name": "Monday",
            "value": 1,
            "tooltip": "Monday is the first working day of a week"
        }, 
        ...
      ] 
     }
]

Co-authored-by: David Chesnut <davech@microsoft.com>
Copy link
Contributor

Learn Build status updates of commit ba0a1dc:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-custom-enums.md ✅Succeeded View
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View
docs/excel/custom-functions-troubleshooting.md ✅Succeeded View

For more details, please refer to the build report.

@alison-mk alison-mk requested a review from davidchesnut July 10, 2025 00:58
Copy link
Contributor

Learn Build status updates of commit 8804a05:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-custom-enums.md ✅Succeeded View
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View
docs/excel/custom-functions-troubleshooting.md ✅Succeeded View

For more details, please refer to the build report.

Copy link
Member

@davidchesnut davidchesnut left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! I added one comment to see if I could combine two sentences and streamline them, but it's optional.

Co-authored-by: David Chesnut <davech@microsoft.com>
Copy link
Contributor

Learn Build status updates of commit be8fd57:

✅ Validation status: passed

File Status Preview URL Details
docs/excel/custom-functions-custom-enums.md ✅Succeeded View
docs/excel/custom-functions-json-autogeneration.md ✅Succeeded View
docs/excel/custom-functions-json.md ✅Succeeded View
docs/excel/custom-functions-troubleshooting.md ✅Succeeded View

For more details, please refer to the build report.

@alison-mk alison-mk merged commit 7f3f5e2 into main Jul 11, 2025
2 checks passed
@alison-mk alison-mk deleted the alison-mk-cf15-streaming branch July 11, 2025 19:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants