Implement a new IDN display policy

components/url_formatter/url_formatter.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // url_formatter contains routines for formatting URLs in a way that can be
 // safely and securely displayed to users. For example, it is responsible
 // for determining when to convert an IDN A-Label (e.g. "xn--[something]")
 // into the IDN U-Label.
 //
 // Note that this formatting is only intended for display purposes; it would
@@ skipping 35 matching lines @@
 // If the scheme is 'http://', it's removed.
 extern const FormatUrlType kFormatUrlOmitHTTP;
 
 // Omits the path if it is just a slash and there is no query or ref.  This is
 // meaningful for non-file "standard" URLs.
 extern const FormatUrlType kFormatUrlOmitTrailingSlashOnBareHostname;
 
 // Convenience for omitting all unecessary types.
 extern const FormatUrlType kFormatUrlOmitAll;
 
-// Creates a string representation of |url|. The IDN host name may be in Unicode
-// if |languages| accepts the Unicode representation. |format_type| is a bitmask
+// Creates a string representation of |url|. The IDN host name is turned to
+// Unicode if the Unicode representation is deemed safe. |languages| is not
+// used any more and will be removed. |format_type| is a bitmask
 // of FormatUrlTypes, see it for details. |unescape_rules| defines how to clean
 // the URL for human readability. You will generally want |UnescapeRule::SPACES|
 // for display to the user if you can handle spaces, or |UnescapeRule::NORMAL|
 // if not. If the path part and the query part seem to be encoded in %-encoded
 // UTF-8, decodes %-encoding and UTF-8.
 //
 // The last three parameters may be NULL.
 //
 // |new_parsed| will be set to the parsing parameters of the resultant URL.
 //
@@ skipping 53 matching lines @@
 inline base::string16 FormatUrl(const GURL& url, const std::string& languages) {
   return FormatUrl(url, languages, kFormatUrlOmitAll, net::UnescapeRule::SPACES,
                    nullptr, nullptr, nullptr);
 }
 
 // Returns whether FormatUrl() would strip a trailing slash from |url|, given a
 // format flag including kFormatUrlOmitTrailingSlashOnBareHostname.
 bool CanStripTrailingSlash(const GURL& url);
 
 // Formats the host in |url| and appends it to |output|.  The host formatter
-// takes the same accept languages component as ElideURL().
+// takes the same accept languages component as ElideURL(), but it does not
+// affect the result. It'll be removed.
 void AppendFormattedHost(const GURL& url,
                          const std::string& languages,
                          base::string16* output);
 
 // Converts the given host name to unicode characters. This can be called for
 // any host name, if the input is not IDN or is invalid in some way, we'll just
 // return the ASCII source so it is still usable.
 //
 // The input should be the canonicalized ASCII host name from GURL. This
 // function does NOT accept UTF-8!
-//
-// |languages| is a comma separated list of ISO 639 language codes. It
-// is used to determine whether a hostname is 'comprehensible' to a user
-// who understands languages listed. |host| will be converted to a
-// human-readable form (Unicode) ONLY when each component of |host| is
-// regarded as 'comprehensible'. Scipt-mixing is not allowed except that
-// Latin letters in the ASCII range can be mixed with a limited set of
-// script-language pairs (currently Han, Kana and Hangul for zh,ja and ko).
-// When |languages| is empty, even that mixing is not allowed.
+// |languages| is not used any more and will be removed.
 base::string16 IDNToUnicode(const std::string& host,
                             const std::string& languages);
 
 // If |text| starts with "www." it is removed, otherwise |text| is returned
 // unmodified.
 base::string16 StripWWW(const base::string16& text);
 
 // Runs |url|'s host through StripWWW().  |url| must be valid.
 base::string16 StripWWWFromHost(const GURL& url);
 
 }  // namespace url_formatter
 
 #endif  // COMPONENTS_URL_FORMATTER_URL_FORMATTER_H_