fix: eliminate starlight-typedoc-plugin warnings with code comments (#557)

Author: seratch

packages/agents-core/src/agent.ts

@@ -150,9 +150,6 @@ export interface AgentConfiguration<
   TContext = UnknownContext,
   TOutput extends AgentOutputType = TextOutput,
 > {
-  /**
-   * The name of the agent.
-   */
   name: string;
 
   /**

packages/agents-core/src/helpers/message.ts

@@ -9,9 +9,9 @@ import {
 /**
  * Creates a user message entry
  *
- * @param input The input message from the user
- * @param options Any additional options that will be directly passed to the model
- * @returns a message entry
+ * @param input The input message from the user.
+ * @param options Any additional options that will be directly passed to the model.
+ * @returns A message entry.
  */
 export function user(
   input: string | UserContent[],
@@ -36,9 +36,9 @@ export function user(
 /**
  * Creates a system message entry
  *
- * @param input The system prompt
- * @param options Any additional options that will be directly passed to the model
- * @returns a message entry
+ * @param input The system prompt.
+ * @param options Any additional options that will be directly passed to the model.
+ * @returns A message entry.
  */
 export function system(
   input: string,
@@ -55,9 +55,9 @@ export function system(
 /**
  * Creates an assistant message entry for example for multi-shot prompting
  *
- * @param input The assistant response
- * @param options Any additional options that will be directly passed to the model
- * @returns a message entry
+ * @param content The assistant response.
+ * @param options Any additional options that will be directly passed to the model.
+ * @returns A message entry.
  */
 export function assistant(
   content: string | AssistantContent[],

packages/agents-core/src/result.ts

@@ -377,9 +377,9 @@ export class StreamedRunResult<
   /**
    * Returns a readable stream of the final text output of the agent run.
    *
-   * @param options - Options for the stream.
-   * @param options.compatibleWithNodeStreams - Whether to use Node.js streams or web standard streams.
    * @returns A readable stream of the final output of the agent run.
+   * @remarks Pass `{ compatibleWithNodeStreams: true }` to receive a Node.js compatible stream
+   * instance.
    */
   toTextStream(): ReadableStream<string>;
   toTextStream(options?: { compatibleWithNodeStreams: true }): Readable;

packages/agents-core/src/run.ts

@@ -1169,11 +1169,8 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
    * @param agent - The starting agent to run.
    * @param input - The initial input to the agent. You can pass a string or an array of
    * `AgentInputItem`.
-   * @param options - The options for the run.
-   * @param options.stream - Whether to stream the run. If true, the run will emit events as the
-   * model responds.
-   * @param options.context - The context to run the agent with.
-   * @param options.maxTurns - The maximum number of turns to run the agent.
+   * @param options - Options for the run, including streaming behavior, execution context, and the
+   * maximum number of turns.
    * @returns The result of the run.
    */
   run<TAgent extends Agent<any, any>, TContext = undefined>(

packages/agents-core/src/runContext.ts

@@ -47,11 +47,11 @@ export class RunContext<TContext = UnknownContext> {
   /**
    * Check if a tool call has been approved.
    *
-   * @param toolName - The name of the tool.
-   * @param callId - The call ID of the tool call.
+   * @param approval - Details about the tool call being evaluated.
    * @returns `true` if the tool call has been approved, `false` if blocked and `undefined` if not yet approved or rejected.
    */
-  isToolApproved({ toolName, callId }: { toolName: string; callId: string }) {
+  isToolApproved(approval: { toolName: string; callId: string }) {
+    const { toolName, callId } = approval;
     const approvalEntry = this.#approvals.get(toolName);
     if (approvalEntry?.approved === true && approvalEntry.rejected === true) {
       logger.warn(
@@ -96,8 +96,8 @@ export class RunContext<TContext = UnknownContext> {
   /**
    * Approve a tool call.
    *
-   * @param toolName - The name of the tool.
-   * @param callId - The call ID of the tool call.
+   * @param approvalItem - The tool approval item to approve.
+   * @param options - Additional approval behavior options.
    */
   approveTool(
     approvalItem: RunToolApprovalItem,

packages/agents-core/src/tool.ts

@@ -151,9 +151,8 @@ export type HostedMCPTool<Context = UnknownContext> = HostedTool & {
 /**
  * Creates a hosted MCP tool definition.
  *
- * @param serverLabel - The label identifying the MCP server.
- * @param serverUrl - The URL of the MCP server.
- * @param requireApproval - Whether tool calls require approval.
+ * @param options - Configuration for the hosted MCP tool, including server connection details
+ * and approval requirements.
  */
 export function hostedMcpTool<Context = UnknownContext>(
   options: {

packages/agents-realtime/src/transportLayer.ts

@@ -131,7 +131,8 @@ export interface RealtimeTransportLayer
 
   /**
    * Resets the conversation history / context to a specific state
-   * @param history - The history to reset to
+   * @param oldHistory - The history that is currently stored on the session.
+   * @param newHistory - The history you want the session to use going forward.
    */
   resetHistory(oldHistory: RealtimeItem[], newHistory: RealtimeItem[]): void;