-
Notifications
You must be signed in to change notification settings - Fork 270
[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
Conversation
Learn Build status updates of commit 28de69d: ✅ Validation status: passed
For more details, please refer to the build report. |
Learn Build status updates of commit 9ae2248: ✅ Validation status: passed
For more details, please refer to the build report. |
Learn Build status updates of commit a094553: ✅ Validation status: passed
For more details, please refer to the build report. |
Learn Build status updates of commit ecbf5e4: ✅ Validation status: passed
For more details, please refer to the build report. |
Learn Build status updates of commit a1193d3: ✅ Validation status: passed
For more details, please refer to the build report. |
Learn Build status updates of commit 8d47130:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | 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.
Learn Build status updates of commit f3b230b:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | 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.
Learn Build status updates of commit 34f0edf:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | 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.
Learn Build status updates of commit 35135cc:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | View | Details | |
docs/excel/custom-functions-troubleshooting.md | 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.
There was a problem hiding this 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 anenums
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 onlyname
,tooltip
, andvalue
, but omits the requiredid
andtype
fields. Add rows forid
(string, Yes) andtype
(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": [
Learn Build status updates of commit 9f399bb:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | View | Details | |
docs/excel/custom-functions-troubleshooting.md | 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.
Learn Build status updates of commit e33bc51:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | View | Details | |
docs/excel/custom-functions-troubleshooting.md | 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.
Learn Build status updates of commit e53207b:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-json-autogeneration.md | View | Details | |
docs/excel/custom-functions-json.md | View | Details | |
docs/excel/custom-functions-troubleshooting.md | 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.
Learn Build status updates of commit 0a6c449:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-troubleshooting.md | 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.
Learn Build status updates of commit 3e8bbb8:
|
File | Status | Preview URL | Details |
---|---|---|---|
docs/excel/custom-functions-troubleshooting.md | 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.
Learn Build status updates of commit c8a0e8b: ✅ Validation status: passed
For more details, please refer to the build report. |
There was a problem hiding this 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.
docs/excel/custom-functions-json.md
Outdated
@@ -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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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": [
{
...
},
]
}
]
There was a problem hiding this comment.
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>
Learn Build status updates of commit ba0a1dc: ✅ Validation status: passed
For more details, please refer to the build report. |
Learn Build status updates of commit 8804a05: ✅ Validation status: passed
For more details, please refer to the build report. |
There was a problem hiding this 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>
Learn Build status updates of commit be8fd57: ✅ Validation status: passed
For more details, please refer to the build report. |
The new custom enums article is added in a separate PR: #5252