Add JSDoc for Conditional Request Headers in Generated SDK Methods

[joheredi]

Description

Enhance the code generator to automatically add JSDoc warnings and guidance for methods that accept conditional request headers (e.g., If-Unmodified-Since, If-Match, If-Modified-Since). This will help developers understand the behavior and how to handle related status codes.

---

Background

Conditional headers control concurrency and caching. When used:

• 412 Precondition Failed occurs if the resource changed since the specified condition.
• 304 Not Modified occurs for GET requests if the resource has not changed.

Currently, our SDK treats these headers as regular headers and does not retry or resolve conflicts automatically. Developers need clear documentation to handle these cases.

---

Scope

• Detect operations that support conditional headers during code generation.
• Inject a standardized JSDoc block for these methods.

---

Proposed JSDoc Template

/**
 * Updates a resource conditionally.
 *
 * **Important:** If you set conditional headers (e.g., `If-Unmodified-Since`, `If-Match`),
 * the service may return:
 * - `412 Precondition Failed` if the resource changed since the specified condition.
 * - `304 Not Modified` for GET requests if the resource has not changed.
 *
 * The SDK does not automatically retry or resolve conflicts.
 * You should handle these status codes in your application logic.
 *
 * @example
 * // Example of using If-Unmodified-Since:
 * await client.updateResource(id, data, {
 *   headers: { "If-Unmodified-Since": lastKnownDate.toUTCString() }
 * });
 *
 * // Handle 412:
 * try {
 *   await client.updateResource(...);
 * } catch (err) {
 *   if (err.statusCode === 412) {
 *     // Refresh resource or prompt user
 *   }
 * }
 */

---

Acceptance Criteria

• Code generator identifies methods that support conditional headers.
• JSDoc template is applied consistently across generated methods.
• Unit tests verify that generated code includes the JSDoc block.
• Documentation updated to explain rationale for this addition.

---

Additional Notes

• Consider making the JSDoc template configurable for future enhancements.
• Ensure this does not break existing linting or formatting rules.