Document the percent_encoding module

[brson]

This module encapsulates a crate-specific pattern that could be explained better.

Some things that might clarify my questions about this module:

• Module level explanation of what "percent encoding" is and the role of EncodeSet
• Module level examples of creating and using encode sets
• Do users ever need to create their own encode sets?
• When do users need to use this module?
• Examples on the free functions and EncodeSet
• Documentation of which characters are in each predefined EncodeSet

[SimonSapin]

Do users ever need to create their own encode sets?

If one doesn’t know whether they need a custom encode set, they probably don’t. This a fairly advanced feature, almost an "escape hatch". While it should be documented in the sense that everything should be documented, it shouldn’t be featured prominently in the module’s or crate’s documentation.

I wish rustdoc was prose-oriented like Sphinx, and let crate authors/maintainers choose what items to show first and generally how to organize docs.