[http-client-js] Improve documentation #6940

joheredi · 2025-04-10T01:18:23Z

Improve code documentation to make it more understandable for AI systems or human developers.

This has been mostly generated by AI and reviewed by me. Appreciate another set of eyes

github-actions · 2025-04-10T01:21:05Z

All changed packages have been documented.

✅ @typespec/http-client-js

Show changes

`@typespec/http-client-js` - internal ✏️

Add code documentation

azure-sdk · 2025-04-10T01:39:22Z

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

qiaozha · 2025-04-10T07:48:55Z

packages/http-client-js/src/components/http-response.tsx

  return (
    <For each={responses.filter((r) => !$.httpResponse.isErrorResponse(r))}>
      {({ statusCode, contentType, responseContent, type }) => {
+        // Extract the body from the response content


Is this also auto generated by AI? how did it know which lines to add and which not?

qiaozha · 2025-04-10T07:54:34Z

packages/http-client-js/src/components/http-response.tsx

 export function HttpResponses(props: HttpResponsesProps) {
-  // Handle response by status code and content type
+  // Obtain and flatten the HTTP responses from the operation, filtering by non-error responses.


Feel like this would be more useful if we could add the typekit description to it?
"Get the responses for the given operation. This function will return an array of responses grouped by status code and content type."

qiaozha · 2025-04-10T08:18:19Z

packages/http-client-js/src/components/transforms/transform-name-policy.ts

 *
- * @param type - The type object that must have a `name` property of type `string`.
+ * @param type - The type object whose name is to be transformed.


is the previous documentation also generated by AI? will it change everytime we use the AI to help us regen the documentation once in a while?
Also, what if the logic has been changed but we forget about improve the documentation?

MaryGao · 2025-04-10T14:48:50Z

packages/http-client-js/src/components/operation-handlers/paging/page-item.tsx

 import { PagingOperation } from "@typespec/compiler";
 import { $ } from "@typespec/compiler/experimental/typekit";
 import { TypeExpression } from "@typespec/emitter-framework/typescript";

+/**
+ * Extracts and returns the element type of the page items array from a paging operation.


interesting, AI is writing the right stuff here.

MaryGao · 2025-04-10T14:55:50Z

packages/http-client-js/src/components/operation-handlers/paging/page-response.tsx

@@ -27,9 +55,15 @@ export function PageResponseDeclaration(props: PageResponseProps) {
    "firstLink",
    "lastLink",
  ];
+
+  // Array to hold validated paging properties extracted from the defined responses.


nit: i may not say validated here, no validation.

Suggested change

// Array to hold validated paging properties extracted from the defined responses.

// Array to hold paging properties extracted from the defined responses.

MaryGao · 2025-04-10T15:04:10Z

packages/http-client-js/src/components/operation-handlers/paging/page-settings.tsx

@@ -1,38 +1,82 @@
+/**
+ * This file defines helper functions and a component to generate TypeScript interface declarations
+ * for page settings used in HTTP operations. It selectively picks accepted paging properties from a


nit: Page setting declarations used in HTTP operations would lead to misleading.

Suggested change

* for page settings used in HTTP operations. It selectively picks accepted paging properties from a

* This file defines helper functions and a component to generate TypeScript interface declarations

* for page settings given the HTTP operation and paging details. It selectively picks accepted paging properties from a

MaryGao · 2025-04-10T15:11:07Z

...ages/http-client-js/src/components/operation-handlers/paging/paginated-operation-handler.tsx

+   * needed to send requests and process responses.
+   *
+   * @param httpOperation - The HTTP operation to handle.
+   * @returns A list of generated components and function declarations for the operation.


nit: the return type is not accurate.

Suggested change

* @returns A list of generated components and function declarations for the operation.

* @returns A JSX list element representing paging relevant interfaces and functions.

MaryGao · 2025-04-10T15:13:11Z

...ages/http-client-js/src/components/operation-handlers/paging/paginated-operation-handler.tsx

@@ -49,12 +73,13 @@ export const PaginatedOperationHandler: OperationHandler = {
    const operationRefkey = ay.refkey(httpOperation.operation);
    const returnType = ay.code`${getPagedAsyncIterableIteratorRefkey()}<${getPageItemTypeName(pagingOperation)},${getPageResponseTypeRefkey(httpOperation)},${getPageSettingsTypeRefkey(httpOperation)}>`;
    const clientContextInterfaceRef = getClientcontextDeclarationRef(client);
+


hah, AI seems talkative‌ in other places, why is it so solient in this method?

MaryGao · 2025-04-10T15:14:18Z

packages/http-client-js/src/components/operation-handlers/paging/page-response.tsx

-  operation: HttpOperation;
-  pagingOperation: PagingOperation;
+  operation: HttpOperation; // The HTTP operation for which the page response is defined.
+  pagingOperation: PagingOperation; // The paging operation containing the output definitions.


is this manually added? the format seems different.

MaryGao · 2025-04-10T15:16:12Z

packages/http-client-js/src/components/operation-handlers/paging/request-send.tsx

@@ -13,42 +18,96 @@ import {
  getOperationParameters,
 } from "../../operation-parameters.jsx";

+/**
+ * Properties for the HttpRequestSend component.
+ * @param httpOperation The HTTP operation to be performed.


is the @param correct here? i notice somewhere else is @property any difference?

MaryGao · 2025-04-10T15:23:12Z

packages/http-client-js/src/components/operation-handlers/paging/request-send.tsx

+   * The following JSX elements embed code generation nodes:
+   *  - HttpRequest.Url generates the code for constructing the URL based on the HTTP operation.
+   *  - HttpRequestOptions configures the request options (headers, query parameters, body, etc.) for the HTTP call.
+   *  - Return statement c and sends the request using the provided client instance:


Suggested change

* - Return statement c and sends the request using the provided client instance:

* - A return statement to send the request using the provided client instance:

MaryGao · 2025-04-10T15:24:04Z

packages/http-client-js/src/components/operation-handlers/paging/request-send.tsx

+   *  - HttpRequest.Url generates the code for constructing the URL based on the HTTP operation.
+   *  - HttpRequestOptions configures the request options (headers, query parameters, body, etc.) for the HTTP call.
+   *  - Return statement c and sends the request using the provided client instance:
+   *    - client.pathUnchecked() is used to select the path without additional type-checking.


interesting, AI even knows our pathUnchecked without type checking.

MaryGao · 2025-04-10T15:25:35Z

packages/http-client-js/src/components/operation-handlers/paging/response-deserialize.tsx

 export interface HttpResponseDeserializeProps {
  httpOperation: HttpOperation;
  responseRefkey: Refkey;
  children?: Children;
 }

+/**
+ * Component that generates a function declaration for deserializing HTTP responses.


Suggested change

* Component that generates a function declaration for deserializing HTTP responses.

* Component that generates a function declaration for deserializing HTTP responses for given paging operation.

MaryGao · 2025-04-10T15:26:45Z

packages/http-client-js/src/components/operation-handlers/paging/response-deserialize.tsx

  const namePolicy = ts.useTSNamePolicy();
  const functionName = namePolicy.getName(httpOperation.operation.name + "Deserialize", "function");
+
+  const responseRefkey = refkey();


aha, is this added by AI?

Improve documentation

68a603a

joheredi requested review from timotheeguerin, timovv, qiaozha, MaryGao, xirzec, bterlson, markcowl, allenjzhang, witemple-msft, chrisradek and AlitzelMendez as code owners April 10, 2025 01:18

Update comments

fb361ea

Merge branch 'main' into joheredi/js-docs

5fb136b

qiaozha reviewed Apr 10, 2025

View reviewed changes

MaryGao reviewed Apr 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[http-client-js] Improve documentation #6940

[http-client-js] Improve documentation #6940

joheredi commented Apr 10, 2025

github-actions bot commented Apr 10, 2025 •

edited

Loading

`@typespec/http-client-js` - internal ✏️

azure-sdk commented Apr 10, 2025 •

edited

Loading

qiaozha Apr 10, 2025

qiaozha Apr 10, 2025

qiaozha Apr 10, 2025

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025 •

edited

Loading

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025 •

edited

Loading

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025

MaryGao Apr 10, 2025

	// Array to hold validated paging properties extracted from the defined responses.
	// Array to hold paging properties extracted from the defined responses.

	* for page settings used in HTTP operations. It selectively picks accepted paging properties from a
	* This file defines helper functions and a component to generate TypeScript interface declarations
	* for page settings given the HTTP operation and paging details. It selectively picks accepted paging properties from a

	* @returns A list of generated components and function declarations for the operation.
	* @returns A JSX list element representing paging relevant interfaces and functions.

	* - Return statement c and sends the request using the provided client instance:
	* - A return statement to send the request using the provided client instance:

	* Component that generates a function declaration for deserializing HTTP responses.
	* Component that generates a function declaration for deserializing HTTP responses for given paging operation.

[http-client-js] Improve documentation #6940

Are you sure you want to change the base?

[http-client-js] Improve documentation #6940

Conversation

joheredi commented Apr 10, 2025

github-actions bot commented Apr 10, 2025 • edited Loading

@typespec/http-client-js - internal ✏️

azure-sdk commented Apr 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MaryGao Apr 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MaryGao Apr 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Apr 10, 2025 •

edited

Loading

`@typespec/http-client-js` - internal ✏️

azure-sdk commented Apr 10, 2025 •

edited

Loading

MaryGao Apr 10, 2025 •

edited

Loading

MaryGao Apr 10, 2025 •

edited

Loading