Update compiler/rustc_span/src/edit_distance.rs

Co-authored-by: David Wood <agile.lion3441@fuligin.ink>

Author: chenyukang

compiler/rustc_span/src/edit_distance.rs

@@ -170,17 +170,20 @@ pub fn find_best_match_for_name(
     find_best_match_for_name_impl(false, candidates, lookup, dist)
 }
 
-/// Find the best match for a give word list
+/// Find the best match for multiple words
 ///
-/// This function is helpfull when we have multiple patterns for candidates, for example:
+/// This function is intended for use when the desired match would never be
+/// returned due to a substring in `lookup` which is superfluous.
 ///
-/// For give keyword `clippy::missing_docs`, we may have multiple candidates:
-/// - `clippy::missing_docs_in_private_items`
-/// - `clippy::erasing_op`
-/// - `missing_docs`
-///
-/// We want to find the best match for the given keyword, strip a prefix to get `missing_docs`,
-/// then call this function with `lookups` as `["clippy::missing_docs", "missing_docs"]`
+/// For example, when looking for the closest lint name to
+/// `clippy:missing_docs`, we would find `clippy::erasing_op`, despite
+/// `missing_docs` existing and being a better suggestion. `missing_docs`
+/// would have a larger edit distance because it does not contain the
+/// `clippy` tool prefix. In order to find `missing_docs`, this function
+/// takes multiple lookup strings, computes the best match for each and 
+/// returns the match which had the lowest edit distance. In our example, 
+/// clippy:missing_docs` and `missing_docs` would be `lookups`, enabling
+/// `missing_docs` to be the best match, as desired.
 pub fn find_best_match_for_names(
     candidates: &[Symbol],
     lookups: &[Symbol],