Add examples to UrlEscapers javadoc

gissuebot commented 9 years ago

Original issue created by mikhail.mazursky on 2014-05-16 at 08:15 AM

Please consider adding usage examples to UrlEscapers javadocs - what method should be used to escape what part of URIs, when consructing them (and also there is application/x-www-form-urlencoded specially for forms). E.g.

To escape username/password components use ... (what?)
To escape URI path segments use urlPathSegmentEscaper();
To escape URI path parameters names use .... (what?)
To escape URI path parameters values use .... (what?)
To escape URI query parameters names use ... (urlFormParameterEscaper()? I'm not sure)
To escape URI query parameters values use ... (urlFormParameterEscaper()? I'm not sure)
To escape URI fragment use urlFragmentEscaper()
When preparing HTML forms (application/x-www-form-urlencoded) use urlFormParameterEscaper()

It looks like a lot of developers are not aware of the subtleties of escaping and such explicit examples can help avoid lots of bugs. For instance, I was not aware about differences of escaping of query params and HTML form parameters. The following article just opened my eyes http://blog.lunatech.com/2009/02/03/what-every-web-developer-must-know-about-url-encoding

gissuebot commented 9 years ago

Original comment posted by kak@google.com on 2014-06-03 at 04:00 PM

(No comment entered for this change.)

Owner: cpovirk@google.com

cpovirk commented 9 years ago

For my reference, we added an incomplete table to the internal Google codebase in CL 100848159. It ended up containing the same entries as this bug report.

google / guava

Add examples to UrlEscapers javadoc #1756