Document Apache HTTP implementations

[jonathanpeppers]

Closes#301

Sources

• Android 6.0 Apache HTTP client removal notice
• AOSP Apache HTTP implementation sources (android-4.4.4_r2)

Validation

• Parsed all 13 changed XML files with System.Xml.XmlDocument.
• Confirmed no To be added. placeholders remain in Org.Apache.Http.Impl or its namespace XML.
• Ran git diff --check.

[Copilot]

Pull request overview

This PR updates the XML documentation for the Org.Apache.Http.Impl namespace to replace To be added. placeholders with meaningful summaries/parameter/return descriptions, aligning the generated API docs with the underlying Apache HTTP implementation types exposed in Mono.Android.

Changes:

• Replaced placeholder summaries across core connection/strategy/factory types in Org.Apache.Http.Impl.
• Added parameter and return-value documentation for key methods/properties (e.g., socket binding, buffer creation, metrics lookups).
• Added a namespace-level summary for Org.Apache.Http.Impl.

Reviewed changes

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

Show a summary per file

File	Description
docs/xml/Org.Apache.Http.Impl/SocketHttpServerConnection.xml	Adds class/member docs for socket-backed HTTP server connections.
docs/xml/Org.Apache.Http.Impl/SocketHttpClientConnection.xml	Adds class/member docs for socket-backed HTTP client connections.
docs/xml/Org.Apache.Http.Impl/NoConnectionReuseStrategy.xml	Documents the “never reuse” connection reuse strategy (one doc accuracy fix requested).
docs/xml/Org.Apache.Http.Impl/HttpConnectionMetricsImpl.xml	Documents connection metrics collection and metric accessors.
docs/xml/Org.Apache.Http.Impl/EnglishReasonPhraseCatalog.xml	Documents English HTTP status reason phrase lookup behavior.
docs/xml/Org.Apache.Http.Impl/DefaultHttpServerConnection.xml	Documents default server connection implementation details.
docs/xml/Org.Apache.Http.Impl/DefaultHttpClientConnection.xml	Documents default client connection implementation details.
docs/xml/Org.Apache.Http.Impl/DefaultHttpResponseFactory.xml	Documents default HTTP response creation APIs.
docs/xml/Org.Apache.Http.Impl/DefaultHttpRequestFactory.xml	Documents default HTTP request creation APIs.
docs/xml/Org.Apache.Http.Impl/DefaultConnectionReuseStrategy.xml	Documents default connection reuse decision logic entry points.
docs/xml/Org.Apache.Http.Impl/AbstractHttpServerConnection.xml	Documents base server connection behavior and extensibility points.
docs/xml/Org.Apache.Http.Impl/AbstractHttpClientConnection.xml	Documents base client connection behavior and extensibility points.
docs/xml/ns-Org.Apache.Http.Impl.xml	Adds a namespace-level summary for Org.Apache.Http.Impl.

---

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

[jonathanpeppers]

@dalexsoto review

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The prior KeepAlive finding is fixed, but three implementation-contract groups remain inaccurate:

• EnglishReasonPhraseCatalog.GetReason ignores locale and requires status 100-599; DetermineLocale ignores context and always returns the default locale.
• DefaultHttpRequestFactory supports only GET/POST/PUT/HEAD/OPTIONS/DELETE/TRACE, throws for methods such as PATCH/CONNECT, and only POST/PUT are entity-enclosing.
• Connection metrics, sockets, addresses, ports, and timeouts can be null or -1 before initialization/binding; the current docs present them as always available.

Please document these concrete behaviors throughout the affected client/server and metrics XML.

[jonathanpeppers]

Addressed all three contract groups from the AOSP implementation: the reason-catalog range and ignored locale, response-factory default locale and ignored context, request-factory method support and entity-enclosing behavior, and nullable/-1 pre-initialization connection values.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The locale, request-method, metrics, and concrete socket fixes are correct, but the abstract client and server SocketTimeout properties still omit the full sentinel contract. Please document positive milliseconds, 0 as disabled, and -1 as undefined consistently on both abstract APIs: AbstractHttpClientConnection.xml and AbstractHttpServerConnection.xml.

[jonathanpeppers]

Addressed the remaining SocketTimeout feedback in 2858857: both abstract client and server properties now document positive millisecond values, 0 as disabled, and -1 as undefined. The 13 changed XML files pass the mdoc ECMA validator, the updated text appears in both generated HTML pages, all retain CRLF endings, and git diff --check passes.

[dalexsoto]

The SocketTimeout docs still conflate getter sentinels with setter-valid values. Getting may return -1 when unavailable or undefined, but the socket-backed setters reject negative values; setting accepts nonnegative milliseconds, with 0 meaning an infinite/disabled timeout. Please separate getter and setter behavior on both abstract properties and both concrete socket implementations.

[jonathanpeppers]

Addressed the getter/setter distinction in bbe5f0c across both abstract properties and both socket-backed implementations. The docs now state that getters may return -1 when unavailable or undefined, while setters accept only nonnegative milliseconds, use 0 for an infinite/disabled timeout, and reject negative values. The XML passes mdoc validation, the text appears in all four generated HTML pages, CRLF is preserved, and git diff --check passes.

[dalexsoto]

SocketTimeout getter sentinels and setter-valid values are now correctly distinguished across all four APIs.

[jonathanpeppers]

Resolved the main merge conflict in 053bba9/987f57e3 by preserving the newer upstream Org.Apache.Http.Impl namespace summary and attribution in full. That namespace file now matches main exactly and has dropped out of the PR diff; the PR remains limited to the 12 intended implementation-type XML files. The affected XML passes mdoc validation, all four reviewed timeout pages still generate correctly, CRLF is preserved, and git diff --check passes.

[dalexsoto]

The conflict resolution preserves current main documentation while retaining all reviewed implementation contracts and timeout fixes.