docs(sdk): add JSDoc to all exported interfaces and types#26277
docs(sdk): add JSDoc to all exported interfaces and types#26277scidomino merged 1 commit intogoogle-gemini:mainfrom
Conversation
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
Summary of ChangesHello, 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 enhancing the maintainability and usability of the SDK by introducing comprehensive documentation across the codebase. By providing clear descriptions, parameter details, and usage examples for core components, this change significantly improves the developer experience for those consuming the SDK. Highlights
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. Footnotes
|
1855b4f to
744ca20
Compare
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive JSDoc documentation to the SDK package, covering core classes and interfaces such as GeminiCliAgent, GeminiCliSession, and Tool. The feedback identifies an opportunity to improve the SdkAgentShell documentation by clarifying that standard error is merged into the standard output stream, which is important for developers using the AgentShellResult interface.
| /** | ||
| * SDK implementation of {@link AgentShell} that executes commands via the | ||
| * core ShellExecutionService, subject to the agent's security policies. | ||
| * | ||
| * Commands that require interactive confirmation will be rejected since | ||
| * no interactive session is available in headless SDK mode. | ||
| */ |
There was a problem hiding this comment.
The documentation for SdkAgentShell is helpful, but it's missing a crucial detail about how stdout and stderr are handled. The current implementation of exec combines both streams into the stdout field of the AgentShellResult and leaves stderr empty, which contradicts the definition of the AgentShellResult interface. This can be misleading for developers who might rely on the stderr field for error handling, leading to incorrect logic. It would be beneficial to add a note about this behavior in the class's JSDoc to prevent confusion.
/**
* SDK implementation of {@link AgentShell} that executes commands via the
* core ShellExecutionService, subject to the agent's security policies.
*
* Commands that require interactive confirmation will be rejected since
* no interactive session is available in headless SDK mode.
*
* @remarks In this implementation, stderr is combined into stdout by the
* underlying ShellExecutionService. As a result, the stderr field of the
* returned {@link AgentShellResult} will be empty, and both output and
* stdout will contain the combined output.
*/744ca20 to
2200165
Compare
…ini-cli) - openai/codex#20564 — Enforce animations=false for screen readers (merge-as-is) - openai/codex#20530 — Support multi-env filesystem tools (merge-after-nits) - BerriAI/litellm#26956 — Fix MCP semantic filter native tool passthrough (merge-after-nits) - google-gemini/gemini-cli#26277 — docs(sdk): add JSDoc to all exports (merge-as-is)
Add comprehensive JSDoc documentation to every exported interface, type, class, and function in the SDK package: - types.ts: SystemInstructions, GeminiCliAgentOptions, AgentFilesystem, AgentShellOptions, AgentShellResult, AgentShell, SessionContext - tool.ts: ModelVisibleError, ToolDefinition, Tool, SdkTool, tool() - skills.ts: SkillReference - agent.ts: GeminiCliAgent, session(), resumeSession() - session.ts: GeminiCliSession, id, initialize(), sendStream() - fs.ts: SdkAgentFilesystem - shell.ts: SdkAgentShell Each doc includes descriptions, @param, @returns, @throws, @typeparam, and @example tags where appropriate. Fixes google-gemini#21505
2200165 to
7e93a5d
Compare
|
I fixed the merge conflict. |
Description
Add comprehensive JSDoc documentation to every exported interface, type, class, and function in the SDK package (
packages/sdk).Changes
packages/sdk/src/types.tsSystemInstructions— documents the static string vs dynamic function patternGeminiCliAgentOptions— documents all 8 configuration propertiesAgentFilesystem— documents the sandboxed filesystem interface and its methodsAgentShellOptions— documents shell execution optionsAgentShellResult— documents all result fields (exitCode, output, stdout, stderr, error)AgentShell— documents the shell execution interfaceSessionContext— documents all 8 context propertiespackages/sdk/src/tool.tsModelVisibleError— documents the error visibility behaviorToolDefinition<T>— documents name, description, inputSchema, sendErrorsToModelTool<T>— documents the action function with @param and @returnsSdkTool<T>— documents the wrapper classtool()— documents the helper factory with @examplepackages/sdk/src/skills.tsSkillReference— documents the skill directory reference typepackages/sdk/src/agent.tsGeminiCliAgent— class-level docs with @examplesession()— @param and @returnsresumeSession()— @param, @returns, @throwspackages/sdk/src/session.tsGeminiCliSession— class-level docsidgetter — documents the session identifierinitialize()— documents the initialization lifecyclesendStream()— documents the streaming API with @examplepackages/sdk/src/fs.tsSdkAgentFilesystem— documents the implementation classpackages/sdk/src/shell.tsSdkAgentShell— documents the implementation classTesting
@param,@returns,@throws,@typeParam,@example){@link}for navigationFixes #21505