docs/api: clean up Upload API docs slightly (#17514)

* docs/api: clean up Upload API docs slightly

Signed-off-by: William Woodruff <[email protected]>

* fixup pluralization docs

Signed-off-by: William Woodruff <[email protected]>

---------

Signed-off-by: William Woodruff <[email protected]>
Co-authored-by: Dustin Ingram <[email protected]>

Author: woodruffw

docs/user/api/upload.md

@@ -27,29 +27,42 @@ POST request with the following fields:
 - `:action` set to `file_upload`
 - `protocol_version` set to `1`
 - `content` with the file to be uploaded and the proper filename
-  (i.e. `my_foo_bar-4.2-cp36-cp36m-manylinux1_x86_64.whl`)
+  (e.g. `my_foo_bar-4.2-cp36-cp36m-manylinux1_x86_64.whl`)
 - One of the following hash digests:
     - `md5_digest` set to the md5 hash of the uploaded file in urlsafe base64
-  with no padding
+      with no padding
     - `sha256_digest` set to the SHA2-256 hash in hexadecimal
     - `blake2_256_digest` set to the Blake2b 256-bit hash in hexadecimal
-- `filetype` set to the type of the artifact, i.e. `bdist_wheel`
-  or `sdist`
-- When used with `bdist_wheel` for `filetype`, `pyversion` must be set to
-  a specific release, i.e. `cp36`, when used with `sdist` it must be set to
-  `source`
-- `metadata_version`, `name` and `version` set according to the
+- `filetype` must be set to the type of the artifact: `bdist_wheel` or `sdist`.
+- `pyversion` must be set to a [Python tag] for `bdist_wheel` uploads,
+   or `source` for `sdist` uploads.
+- `metadata_version`, `name` and `version` must be set according to the
   [Core metadata specifications]
 - `attestations` can be set to a JSON array of [attestation objects].
   PyPI will reject the upload if it can't verify each of the
   supplied attestations.
-- You can set any other field from the [Core metadata specifications]
-  All fields need to be renamed to lowercase and hyphens need to replaced
-  by underscores. So instead of "`Description-Content-Type`" the field must be
-  named "`description_content_type`". Note that adding a field
-  "`Description-Content-Type`" will not raise an error but will be silently
-  ignored.
+- You can set any other field from the [Core metadata specifications].
+
+    All fields need to be renamed to lowercase and hyphens need to replaced
+    by underscores. Additionally, multiple-use fields (like `Classifier`)
+    are pluralized (e.g. `classifiers`) with some limited exceptions
+    noted below:
+
+    | Metadata field | Form field |
+    |----------------|------------|
+    | `Platform` | `platform` (**not** `platforms`) |
+    | `Supported-Platform` | `supported_platform` (**not** `supported_platforms`) |
+    | `License-File` | `license_file` (**not** `license_files`) |
+
+
+    !!! warning
+
+        The transformation above *must* be performed.
+        Sending a form field like `Description-Content-Type` will not raise an
+        error but will be **silently ignored**.
 
 [attestation objects]: ./integrity.md#concepts
 
 [Core metadata specifications]: https://packaging.python.org/specifications/core-metadata
+
+[Python tag]: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#python-tag