Document Apache HTTP authentication APIs

[jonathanpeppers]

Summary

• Documented source-derived authentication behavior in Org.Apache.Http.Impl.Auth.
• Kept JNI plumbing and signature-only constructor placeholders unchanged where AOSP provides no meaningful API prose.

Refs #311

Sources

• Android platform reference URLs for this removed Apache HTTP API now redirect to the Android 6.0 Apache HTTP client removal notice.
• AOSP Apache HTTP authentication sources supplied the authoritative behavior for the documented APIs; the namespace entry includes explicit CC BY 2.5 attribution.

Validation

• Parsed all eleven scoped XML files successfully.
• Confirmed CRLF line endings and ran git diff --check.
• Confirmed the diff changes only docs/xml/Org.Apache.Http.Impl.Auth/ and docs/xml/ns-Org.Apache.Http.Impl.Auth.xml.
• 99 scoped To be added. placeholders remain in JNI/runtime plumbing and constructors without meaningful authoritative prose, so this PR references rather than closes Add XML documentation for Org.Apache.Http.Impl.Auth #311.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

docs/xml/Org.Apache.Http.Impl.Auth/BasicScheme.xml: IsComplete says completion occurs after the challenge is answered, but the implementation sets the flag while processing the challenge, before generating a response. Please document that it becomes true after the Basic challenge has been processed.

[jonathanpeppers]

Addressed the requested correction in ee95d0d: BasicScheme.IsComplete now states that it becomes true after a Basic challenge has been processed, matching the AOSP implementation.

[Copilot]

Pull request overview

This PR improves the API reference documentation for the legacy Org.Apache.Http.Impl.Auth namespace by replacing To be added. placeholders with source-derived behavior descriptions (with AOSP/CC BY 2.5 attribution), while leaving JNI plumbing/signature-only placeholders intact where authoritative prose isn’t available.

Changes:

• Replaced class/member To be added. placeholders with RFC/AOSP-based descriptions across key auth scheme types (Basic, Digest, NTLM, and shared base types).
• Added a namespace-level summary and remarks including a direct link to AOSP sources and CC BY 2.5 attribution.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/xml/Org.Apache.Http.Impl.Auth/UnsupportedDigestAlgorithmException.xml	Replaces the type summary placeholder (but the new summary content appears incorrect for this exception).
docs/xml/Org.Apache.Http.Impl.Auth/RFC2617Scheme.xml	Documents shared RFC 2617 scheme behavior and parameter parsing APIs.
docs/xml/Org.Apache.Http.Impl.Auth/NTLMScheme.xml	Documents NTLM exchange behavior, including completion/connection-based semantics.
docs/xml/Org.Apache.Http.Impl.Auth/NTLMEngineException.xml	Adds a descriptive exception summary for NTLM protocol failures.
docs/xml/Org.Apache.Http.Impl.Auth/INTLMEngine.xml	Documents the NTLM engine interface and message generation methods.
docs/xml/Org.Apache.Http.Impl.Auth/DigestSchemeFactory.xml	Documents Digest scheme factory creation behavior and parameter usage.
docs/xml/Org.Apache.Http.Impl.Auth/DigestScheme.xml	Documents Digest scheme behavior, nonce generation, and properties.
docs/xml/Org.Apache.Http.Impl.Auth/BasicSchemeFactory.xml	Documents Basic scheme factory creation behavior and parameter usage.
docs/xml/Org.Apache.Http.Impl.Auth/BasicScheme.xml	Documents Basic scheme behavior including overload semantics and properties.
docs/xml/Org.Apache.Http.Impl.Auth/AuthSchemeBase.xml	Documents shared challenge processing behaviors for auth schemes.
docs/xml/ns-Org.Apache.Http.Impl.Auth.xml	Adds namespace summary plus AOSP source link and CC BY 2.5 attribution.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The prior BasicScheme.IsComplete correction and accepted placeholder scope are preserved, but two current contracts are still incorrect:

• DigestScheme.IsComplete is not true for every non-stale case; it becomes true only after a Digest challenge is processed and remains false for a new scheme.
• ParseChallenge.len is the exclusive end index, not a character count, in AuthSchemeBase, RFC2617Scheme, and NTLMScheme; describing it as a length can make overrides parse the wrong range.

See DigestScheme.xml and AuthSchemeBase.xml.