Document Apache HTTP cookie implementations

[jonathanpeppers]

Summary

• Replaced all 699 placeholder XML documentation entries in Org.Apache.Http.Impl.Cookie.
• Added namespace, type, member, parameter, return-value, and binding-infrastructure documentation without changing other namespaces.

Closes#271

Sources

• AOSP Apache HTTP cookie sources: https://android.googlesource.com/platform/external/apache-http/+/refs/heads/main/src/org/apache/http/impl/cookie/
• Existing Android platform reference links and AOSP Creative Commons Attribution 2.5 notices retained in the XML.

Validation

• Parsed all 34 scoped XML files successfully.
• Confirmed zero To be added placeholders in the scoped namespace.
• Confirmed CRLF line endings and a clean git diff --check.

[Copilot]

Pull request overview

This PR replaces placeholder XML documentation in Org.Apache.Http.Impl.Cookie with descriptive namespace/type/member/parameter/return-value docs, aligning the generated API docs with the underlying Apache HTTP cookie implementations.

Changes:

• Replaced To be added. placeholders across the Org.Apache.Http.Impl.Cookie namespace.
• Added/updated summaries, parameter docs, return/value docs, and binding-infrastructure (JNI peer/threshold) documentation.
• Documented cookie policies/specs (RFC 2109, RFC 2965, Netscape draft, browser-compat, best-match) and related handlers/utilities.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965VersionAttributeHandler.xml	Replaced placeholders with docs for the RFC 2965 Version attribute handler.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965SpecFactory.xml	Documented factory for creating RFC 2965 cookie specs.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965Spec.xml	Documented RFC 2965 cookie parsing/validation/matching/formatting behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965PortAttributeHandler.xml	Documented RFC 2965 Port attribute parsing/validation/matching.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965DomainAttributeHandler.xml	Documented RFC 2965 Domain attribute parsing/validation/matching.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965DiscardAttributeHandler.xml	Documented RFC 2965 Discard attribute handler members.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2965CommentUrlAttributeHandler.xml	Documented RFC 2965 CommentURL attribute parsing and application.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2109VersionHandler.xml	Documented RFC 2109 Version attribute parsing/validation behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2109SpecFactory.xml	Documented factory for creating RFC 2109 cookie specs.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2109Spec.xml	Documented RFC 2109 cookie parsing/validation/matching/formatting behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/RFC2109DomainHandler.xml	Documented RFC 2109 domain validation/matching rules.
docs/xml/Org.Apache.Http.Impl.Cookie/NetscapeDraftSpecFactory.xml	Documented factory for creating Netscape draft cookie specs.
docs/xml/Org.Apache.Http.Impl.Cookie/NetscapeDraftSpec.xml	Documented Netscape draft cookie spec parsing/formatting and related members.
docs/xml/Org.Apache.Http.Impl.Cookie/NetscapeDraftHeaderParser.xml	Documented Netscape draft header parsing API and default parser instance.
docs/xml/Org.Apache.Http.Impl.Cookie/NetscapeDomainHandler.xml	Documented Netscape draft domain validation/matching rules.
docs/xml/Org.Apache.Http.Impl.Cookie/DateUtils.xml	Documented cookie date formatting/parsing utilities and supported date patterns.
docs/xml/Org.Apache.Http.Impl.Cookie/DateParseException.xml	Documented exception surfaced for unparseable cookie date strings.
docs/xml/Org.Apache.Http.Impl.Cookie/CookieSpecBase.xml	Documented shared base behavior for parsing/matching/validating cookie specs.
docs/xml/Org.Apache.Http.Impl.Cookie/BrowserCompatSpecFactory.xml	Documented factory for browser-compatible cookie specs.
docs/xml/Org.Apache.Http.Impl.Cookie/BrowserCompatSpec.xml	Documented browser-compatible cookie parsing/formatting and date-pattern behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/BestMatchSpecFactory.xml	Documented factory for best-match cookie spec selection.
docs/xml/Org.Apache.Http.Impl.Cookie/BestMatchSpec.xml	Documented best-match policy selection and cookie parsing/validation behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicSecureHandler.xml	Documented Secure attribute parsing/behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicPathHandler.xml	Documented Path attribute parsing/validation/matching behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicMaxAgeHandler.xml	Documented Max-Age parsing and expiry-date derivation behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicExpiresHandler.xml	Documented Expires parsing into a cookie expiry date.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicDomainHandler.xml	Documented conventional Domain attribute parsing/validation/matching.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicCommentHandler.xml	Documented Comment attribute parsing/behavior.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicClientCookie2.xml	Documented RFC 2965 extensions (discard/ports/comment URL) on client cookies.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicClientCookie+InterfaceConsts.xml	Documented standard attribute-name constants used by client cookies.
docs/xml/Org.Apache.Http.Impl.Cookie/BasicClientCookie.xml	Documented mutable client cookie behavior, attributes, and helpers.
docs/xml/Org.Apache.Http.Impl.Cookie/AbstractCookieSpec.xml	Documented base cookie spec dispatch/registration model for attribute handlers.
docs/xml/Org.Apache.Http.Impl.Cookie/AbstractCookieAttributeHandler.xml	Documented default behavior for cookie attribute handlers (parse/match/validate).
docs/xml/ns-Org.Apache.Http.Impl.Cookie.xml	Documented the namespace purpose and scope.

---

💡 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]

Four cookie-contract groups remain incorrect:

• RFC2109Spec.VersionHeader returns null; Cookie2 is emitted by RFC2965.
• AbstractCookieSpec.GetAttribHandler throws IllegalStateException when missing, rather than returning null.
• Several parameter descriptions are copied from unrelated operations (BasicClientCookie, DateUtils.startDate, RFC2109 formatting, RFC2965 domain matching).
• Five FormatCookies methods return IList<IHeader>, not a single header/value.

Please replace these copied descriptions with the Apache/AOSP implementation-specific contracts.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The VersionHeader, GetAttribHandler, and collection-return fixes are correct, but three groups remain:

• BasicClientCookie expiry-date parameters still describe formatting instead of comparison/assignment.
• Sixteen other parameter descriptions still identify the wrong input roles across cookie specs and handlers.
• RFC2965 CommentURL/Discard/Version handlers claim validation or conditional matching although validation is empty and matching is always true; several parsers mutate only ISetCookie2 implementations.

Please replace the remaining templates with the concrete Apache/AOSP behavior.

[dalexsoto]

Six cookie-contract issues remain:

• RFC2109 version parsing accepts negative integers; validation rejects them later.
• Blank paths are replaced with /.
• RFC2965 port parsing requires ISetCookie2 and a nonblank value.
• Basic and RFC2109 domain handlers assign values unchanged rather than normalizing them.
• BestMatchSpec.oneHeader affects only versioned cookies handled by RFC2965.
• ContainsAttribute tests for a non-null mapped value, so present null-valued attributes can return false.

Please align these summaries and parameters with the Apache/AOSP implementations.

[jonathanpeppers]

@dalexsoto review

[jonathanpeppers]

@dalexsoto review