Merge pull request #2652 from lachlan-roberts/jetty-9.4.x-2398-MultiPartFormInputStream-Charset-Documentation

Issue #2398 - MultiPart Charset Encoding

jetty-server/src/main/java/org/eclipse/jetty/server/Request.java

@@ -2349,11 +2349,16 @@ public class Request implements HttpServletRequest
                 }
             }
 
-            // charset should be:
-            //  1. the charset set in the parts content type; else
-            //  2. the default charset set in the _charset_ part; else
-            //  3. the default charset set in the request.setCharacterEncoding; else
-            //  4. the default charset set to UTF_8
+            /*
+            Select Charset to use for this part. (NOTE: charset behavior is for the part value only and not the part header/field names)
+                1. Use the part specific charset as provided in that part's Content-Type header; else
+                2. Use the overall default charset. Determined by:
+                    a. if part name _charset_ exists, use that part's value.
+                    b. if the request.getCharacterEncoding() returns a value, use that.
+                        (note, this can be either from the charset field on the request Content-Type
+                        header, or from a manual call to request.setCharacterEncoding())
+                    c. use utf-8.
+             */
             Charset defaultCharset;
             if (_charset_ != null)
                 defaultCharset = Charset.forName(_charset_);