Add descriptive comments to API members #1810
Conversation
Changed comments for `secrets` property in various files from `/*` to `/**` to ensure they are picked up by documentation generators. Also updated `Expression` class comment in `src/params/types.ts` to be a JSDoc comment. Co-authored-by: egilmorez <5544707+egilmorez@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
Summary of ChangesHello @egilmorez, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request focuses on improving the generated API reference documentation by converting specific code comments from standard block comments to JSDoc format. The primary goal is to ensure that important details about the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request correctly converts block comments to JSDoc comments across multiple files to improve API documentation generation. The changes are consistent and achieve the stated goal. I've added a few suggestions to further enhance the JSDoc comments for the secrets property by making them more descriptive and linking to relevant types. This will provide more context for developers using the generated documentation.
| /** | ||
| * Secrets to bind to a function instance. | ||
| */ |
There was a problem hiding this comment.
While converting this to a JSDoc comment is a good step, the comment itself could be more descriptive to improve the generated documentation. Consider expanding it to explain what types of values are supported for secrets and linking to the SupportedSecretParam type for more details.
/**
* Specifies secrets to be made available to the function instance.
*
* Values can be strings representing the secret name, or `SecretParam`
* or `JsonSecretParam` objects for more advanced configuration.
* See {@link SupportedSecretParam}.
*/| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
To improve the generated API documentation, consider making this comment more descriptive. You could explain the supported types for secrets and link to SupportedSecretParam for further details.
/**
* Specifies secrets to be made available to the function.
*
* Values can be strings representing the secret name, or `SecretParam`
* or `JsonSecretParam` objects for more advanced configuration.
* See {@link SupportedSecretParam}.
*/| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
This comment could be enhanced for better documentation. Providing more details on the supported secret types and a link to SupportedSecretParam would be beneficial for users.
| /** | |
| * Secrets to bind to a function. | |
| */ | |
| /** | |
| * Secrets to bind to a function. | |
| * | |
| * Values can be strings representing the secret name, or `SecretParam` | |
| * or `JsonSecretParam` objects for more advanced configuration. | |
| * See {@link SupportedSecretParam}. | |
| */ |
| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
For clearer API documentation, it would be helpful to expand this comment. You could detail the supported formats for secrets and include a JSDoc link to the SupportedSecretParam type.
| /** | |
| * Secrets to bind to a function. | |
| */ | |
| /** | |
| * Secrets to bind to a function. | |
| * | |
| * Values can be strings representing the secret name, or `SecretParam` | |
| * or `JsonSecretParam` objects for more advanced configuration. | |
| * See {@link SupportedSecretParam}. | |
| */ |
| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
To make the documentation more helpful, consider expanding this comment to describe the valid types for secrets and add a link to SupportedSecretParam.
| /** | |
| * Secrets to bind to a function. | |
| */ | |
| /** | |
| * Secrets to bind to a function. | |
| * | |
| * Values can be strings representing the secret name, or `SecretParam` | |
| * or `JsonSecretParam` objects for more advanced configuration. | |
| * See {@link SupportedSecretParam}. | |
| */ |
| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
This comment can be improved for better clarity in the generated documentation. I suggest adding details about the supported secret formats and linking to the SupportedSecretParam type.
/**
* Secrets to bind to a function.
*
* Values can be strings representing the secret name, or `SecretParam`
* or `JsonSecretParam` objects for more advanced configuration.
* See {@link SupportedSecretParam}.
*/| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
For more comprehensive API documentation, you could enhance this comment by explaining the different ways secrets can be specified and including a link to SupportedSecretParam.
/**
* Secrets to bind to a function.
*
* Values can be strings representing the secret name, or `SecretParam`
* or `JsonSecretParam` objects for more advanced configuration.
* See {@link SupportedSecretParam}.
*/| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
To improve documentation, this comment could be more descriptive. It would be useful to mention the supported types for secrets and link to SupportedSecretParam.
| /** | |
| * Secrets to bind to a function. | |
| */ | |
| /** | |
| * Secrets to bind to a function. | |
| * | |
| * Values can be strings representing the secret name, or `SecretParam` | |
| * or `JsonSecretParam` objects for more advanced configuration. | |
| * See {@link SupportedSecretParam}. | |
| */ |
| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
This comment could be expanded to provide more value in the API documentation. Consider adding information about the supported secret types and a link to SupportedSecretParam.
| /** | |
| * Secrets to bind to a function. | |
| */ | |
| /** | |
| * Secrets to bind to a function. | |
| * | |
| * Values can be strings representing the secret name, or `SecretParam` | |
| * or `JsonSecretParam` objects for more advanced configuration. | |
| * See {@link SupportedSecretParam}. | |
| */ |
| /** | ||
| * Secrets to bind to a function. | ||
| */ |
There was a problem hiding this comment.
For better documentation, you could make this comment more descriptive by explaining the supported secret formats and linking to the SupportedSecretParam type.
| /** | |
| * Secrets to bind to a function. | |
| */ | |
| /** | |
| * Secrets to bind to a function. | |
| * | |
| * Values can be strings representing the secret name, or `SecretParam` | |
| * or `JsonSecretParam` objects for more advanced configuration. | |
| * See {@link SupportedSecretParam}. | |
| */ |
Updated `secrets` property comments in various files from `/*` to `/**` to ensure they are picked up by documentation generators. Added JSDoc comments to `MemoryOption`, `VpcEgressSetting`, and `IngressSetting` union members in `src/v2/options.ts`. Added JSDoc for `onCallGenkit` and clarified `CallableOptions.cors` behavior in `src/v2/providers/https.ts`. Updated `Expression` class comment in `src/params/types.ts` to be a JSDoc comment. Updated `FailurePolicy` documentation in `src/v1/function-configuration.ts`. Co-authored-by: egilmorez <5544707+egilmorez@users.noreply.github.com>
1 participant
Updated
secretsproperty comments in multiple files andExpressionclass comment insrc/params/types.tsto be JSDoc comments (/**). This ensures they are included in the generated API reference documentation.Files modified:
src/v2/options.tssrc/v2/providers/alerts/alerts.tssrc/v2/providers/https.tssrc/v2/providers/eventarc.tssrc/v2/providers/database.tssrc/v2/providers/pubsub.tssrc/v2/providers/storage.tssrc/v2/providers/tasks.tssrc/v2/providers/identity.tssrc/v1/function-configuration.tssrc/params/types.tsPR created automatically by Jules for task 808976492170626211 started by @egilmorez