Document Java emitter diagnostics

.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http-client-java"
+---
+
+Add reference documentation for Java emitter diagnostics.

packages/http-client-java/emitter/src/diagnostics/auth-scheme-not-supported.md

@@ -0,0 +1,57 @@
+This diagnostic is issued when an authentication scheme cannot be represented by the selected Java client flavor.
+
+## Impact
+
+The generated client may omit the scheme or fall back to a less specific credential type.
+
+## ❌ Incorrect Usage
+
+### API key outside a header
+
+```typespec
+@service
+@useAuth(ApiKeyAuth<ApiKeyLocation.query, "api-key">)
+namespace Contoso;
+```
+
+### Basic authentication for an Azure client
+
+```typespec
+@service
+@useAuth(BasicAuth)
+namespace Contoso;
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+```
+
+## Diagnostic Message
+
+The message identifies the unsupported scheme, location, or flavor. For example:
+
+```text
+ApiKey auth is currently only supported for ApiKeyLocation.header.
+```
+
+## ✅ How to Fix
+
+Use OAuth2 authentication.
+
+```typespec
+@service
+@useAuth(OAuth2Auth<[OAuthFlow]>)
+namespace Contoso;
+
+model OAuthFlow {
+  type: OAuth2FlowType.clientCredentials;
+  tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token";
+  scopes: ["https://contoso.com/.default"];
+}
+```
+
+## Suppression
+
+Do not suppress this warning unless custom code will provide the intended authentication behavior.

packages/http-client-java/emitter/src/diagnostics/client-required-false.md

@@ -0,0 +1,37 @@
+This diagnostic is issued when the Java `clientRequired` client option is explicitly set to `false`.
+
+## Impact
+
+Java client generation fails because the option only supports promoting a parameter to required; it cannot make a required parameter optional.
+
+## ❌ Incorrect Usage
+
+```typespec
+model ReadOptions {
+  @query filter: string;
+}
+
+op read(...ReadOptions): void;
+
+@@clientOption(ReadOptions.filter, "clientRequired", false, "java");
+```
+
+## Diagnostic Message
+
+```text
+Client option 'clientRequired' can only be set to 'true'.
+```
+
+## ✅ How to Fix
+
+Remove the client option, or set it to `true` for an optional TypeSpec parameter that must be required in the Java client.
+
+```typespec
+model ReadOptions {
+  @query filter?: string;
+}
+
+op read(...ReadOptions): void;
+
+@@clientOption(ReadOptions.filter, "clientRequired", true, "java");
+```

packages/http-client-java/emitter/src/diagnostics/constant-header-in-response-removed.md

@@ -0,0 +1,29 @@
+This diagnostic is issued when a response content-type header has a constant value and the Java emitter removes it from the generated response-header model.
+
+## Impact
+
+The constant header is not generated as a property in the response-header model because its value cannot vary.
+
+## Example Usage
+
+```typespec
+op read(): {
+  @statusCode statusCode: 200;
+  @header contentType: "application/json";
+  @body body: Widget;
+};
+```
+
+## Diagnostic Message
+
+```text
+Constant header 'content-type' is removed from response headers.
+```
+
+## How to Address
+
+No change is required. The TypeSpec definition is valid, and the warning only explains why the generated response-header model does not contain a property for this header.
+
+## Suppression
+
+It is safe to ignore or suppress this warning when the constant header does not need to be exposed as a property.

packages/http-client-java/emitter/src/diagnostics/convenience-api-not-generated.md

@@ -0,0 +1,51 @@
+This diagnostic is issued when the Java emitter cannot form a safe convenience-method signature.
+
+## Impact
+
+The protocol API remains available, but the convenience API is omitted for the operation.
+
+## Multiple Content Types
+
+```typespec
+@post
+op upload(@body data: bytes, @header contentType: "application/octet-stream" | "image/png"): void;
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+```
+
+This TypeSpec definition is valid. Customize the generated Java library to add a convenience API with the appropriate method signature and behavior for the operation. The generated protocol API can be used as the underlying implementation.
+
+## JSON Merge Patch Without Stream-Style Serialization
+
+```typespec
+@patch
+op update(@header contentType: "application/merge-patch+json", @body body: WidgetPatch): void;
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+    stream-style-serialization: false
+```
+
+Enable stream-style serialization:
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    flavor: azure
+    stream-style-serialization: true
+```
+
+## Diagnostic Message
+
+The message identifies either multiple content types or JSON merge patch as the reason the convenience API was not generated.
+
+## Suppression
+
+For multiple content types, suppress the warning after adding the required convenience API customization, or when a protocol-only API surface is intentional. Do not suppress the JSON merge patch warning; enable stream-style serialization instead.

packages/http-client-java/emitter/src/diagnostics/empty-name.md

@@ -0,0 +1,29 @@
+This diagnostic is issued when TCGC supplies a model without a usable generated name.
+
+## Impact
+
+Java client generation stops because every emitted Java model requires a class name.
+
+## ❌ Incorrect Usage
+
+The diagnostic is generally caused by an anonymous or synthesized model shape for which the SDK model did not produce a name. There is no single TypeSpec construct that always triggers it.
+
+## Diagnostic Message
+
+```text
+Name from TCGC is empty.
+```
+
+## ✅ How to Fix
+
+Give anonymous request or response shapes an explicit model name and reference that model from the operation.
+
+```typespec
+model WidgetResponse {
+  value: string;
+}
+
+op getWidget(): WidgetResponse;
+```
+
+If all involved models are already named, update the emitter dependencies and report a minimal reproduction.

packages/http-client-java/emitter/src/diagnostics/header-parameter-format-not-supported.md

@@ -0,0 +1,33 @@
+This diagnostic is issued when an array-valued header uses any collection format other than CSV. The Java emitter supports only comma-delimited arrays for header parameters.
+
+## Impact
+
+The requested header serialization format is ignored, which can produce a request that does not match the service contract.
+
+## ❌ Incorrect Usage
+
+```typespec
+op read(
+  @header
+  @encode(ArrayEncoding.pipeDelimited)
+  values: string[],
+): void;
+```
+
+## Diagnostic Message
+
+```text
+Header parameter format '<format>' is not supported.
+```
+
+## ✅ How to Fix
+
+Use the default comma-delimited header representation.
+
+```typespec
+op read(@header values: string[]): void;
+```
+
+## Suppression
+
+This warning should not be suppressed. Change the service contract or header encoding to CSV.

packages/http-client-java/emitter/src/diagnostics/invalid-api-version.md

@@ -0,0 +1,40 @@
+This diagnostic is issued when the `api-version` emitter option is neither a declared service version nor `latest` or `all`.
+
+## Impact
+
+The requested API-version projection cannot be selected, so Java client generation fails.
+
+## ❌ Incorrect Usage
+
+```typespec
+@service
+@versioned(Versions)
+namespace Contoso;
+
+enum Versions {
+  v1,
+  v2,
+}
+```
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    api-version: v3
+```
+
+## Diagnostic Message
+
+```text
+Invalid api-version option: 'v3'. The value should be an api-version, 'latest', or 'all'.
+```
+
+## ✅ How to Fix
+
+Use a version declared by the service, or use `latest` or `all`.
+
+```yaml
+options:
+  "@typespec/http-client-java":
+    api-version: v2
+```

packages/http-client-java/emitter/src/diagnostics/invalid-java-namespace.md

@@ -0,0 +1,33 @@
+This diagnostic is issued when a generated Java package segment is a reserved Java keyword.
+
+## Impact
+
+The emitter appends `namespace` to the reserved package segment, so the generated package differs from the requested namespace.
+
+## ❌ Incorrect Usage
+
+```typespec
+@service
+namespace Contoso.Public;
+```
+
+The derived Java namespace contains the reserved keyword `public`.
+
+## Diagnostic Message
+
+```text
+Namespace 'contoso.public' contains reserved Java keywords, replaced it with 'contoso.publicnamespace'.
+```
+
+## ✅ How to Fix
+
+Rename the TypeSpec namespace or configure a Java namespace that does not contain Java keywords.
+
+```typespec
+@service
+namespace Contoso.PublicApi;
+```
+
+## Suppression
+
+Suppress the warning only when the adjusted package name is intentionally accepted.

packages/http-client-java/emitter/src/diagnostics/invalid-java-sdk-dependency.md

@@ -0,0 +1,27 @@
+This diagnostic is issued when the Java emitter cannot find a supported JDK, Java runtime, or Apache Maven installation.
+
+## Impact
+
+Java client generation cannot run because the generator process depends on these tools.
+
+## ❌ Incorrect Usage
+
+The emitter is run in an environment where `javac`, `java`, or `mvn` is missing from `PATH`, or where Java is older than the required version.
+
+## Diagnostic Message
+
+The message identifies the missing tool or unsupported Java version, for example:
+
+```text
+Java Development Kit (JDK) is not found in PATH. Please install JDK 17 or above.
+```
+
+## ✅ How to Fix
+
+Install JDK 17 or later and Apache Maven, add their executable directories to `PATH`, and verify:
+
+```shell
+javac -version
+java -version
+mvn -version
+```