PEP 727: update with latest implementation and feedback from discussion

[tiangolo]

• I updated the PEP to use a single class Doc(), no function doc().
• I removed the section about "Additional Scenarios" as it seems it was creating more confusion than help.
• I made it more explicit that "support" comes in at least two ways, editing and rendering.
• I added explicit information about using type aliases and re-using documentation strings via type aliases.
• I tried to clarify what Annotated documents, and how it would be overridden by wrapping type aliases in Annotated.
• I made the argument to Doc() positional only.
• I added a simpler bullet point list of the features this would address that are not addressed by current docstring conventions.
• I added a simple note to suggest to render the docstring first and the parameter documentation later, or to allow configuring.
• I updated several sections based on feedback from several in the discussion.
• I updated the rejected ideas.
• I added a short survey of how other languages document these things.

---

📚 Documentation preview 📚: https://pep-previews--3459.org.readthedocs.build/

[JelleZijlstra]

Looks good, a few formatting nits