Thanks for adding this — the clarification about Logger reflecting Feign's Request rather than the wire request is a genuinely useful thing to document, and I confirmed the core claim is accurate (Logger.logRequest is called in SynchronousMethodHandler before client.execute, so the request logged really can differ from what goes over the wire).

Two things before merging:

1. The doc points at {@link Client.Default}, but that class is @Deprecated (see its javadoc: "use DefaultClient instead"). Feign.Builder actually defaults to new DefaultClient(...), and the restricted-header-dropping behavior you're describing lives in DefaultClient (e.g. the Content-Length: 0 handling around line 228), not in the deprecated wrapper. Please repoint the {@link} to DefaultClient.

2. Consider moving the detailed JDK-specific rationale (the HttpURLConnection restricted-headers behavior, sun.net.http.allowRestrictedHeaders, specific header names) onto DefaultClient's own class javadoc, with a short pointer from Logger's doc ("see {@link DefaultClient} for a concrete example"). That keeps the detail next to the code that actually causes it, where someone touching DefaultClient's header handling would be looking.

Happy to merge once the class reference is fixed.

Friendly ping: the 09-04 review is still open:

1. Link DefaultClient instead of the deprecated Client.Default.
2. (optional) Move the JDK-specific detail to DefaultClient's javadoc and keep a short pointer from Logger.

There's also an accuracy issue. The final clause says a restricted header "can appear in the log without being present in the outgoing request". That isn't true for any of the examples. Host and Connection are always sent by the JDK. Content-Length is passed to setFixedLengthStreamingMode or computed by the JDK. In every case the header is on the wire, possibly with a different value, so please say "the value on the wire may differ". You could also mention that DefaultClient adds Accept: */* when it's missing, and that gzip/deflate changes the body.