[clangd] NFC: Document URIDistance

[kbobyrev]

Summary

URIDistance constructor should mention that Sources must contain *absolute paths*, not URIs. This is not very clear when looking at the interface, especially given that distance(...) accepts URI, not an absolute path which can give the wrong impression.

[sammccall]

clang-tools-extra/clangd/FileDistance.h

69

memoizes is correct here
https://en.wikipedia.org/wiki/Memoization

92

The constructor doesn't do any computation, thus there's nothing to memoize.

I'd suggest dropping the second sentence here, that's the only noteworthy thing specific to this constructor.

[kbobyrev]

clang-tools-extra/clangd/FileDistance.h

92

Sorry, did you mean dropping the *first sentence* here? The second one seems to be the one you describe.

clang-tools-extra/clangd/FileDistance.h

 struct SourceParams {
   // Base cost for paths starting at this source.
   unsigned Cost = 0;
   // Limits the number of upwards traversals allowed from this source.
   unsigned MaxUpTraversals = std::numeric_limits<unsigned>::max();
 };
 
 // Supports lookups to find the minimum distance to a file from any source.
 // This object should be reused, it memoizes intermediate computations.
 class FileDistance {
 public:
   static constexpr unsigned Unreachable = std::numeric_limits<unsigned>::max();
 
   FileDistance(llvm::StringMap<SourceParams> Sources,
                const FileDistanceOptions &Opts = {});
 
   // Computes the minimum distance from any source to the file path.
   unsigned distance(llvm::StringRef Path);
 
 private:
   // Costs computed so far. Always contains sources and their ancestors.
   // We store hash codes only. Collisions are rare and consequences aren't dire.
   llvm::DenseMap<llvm::hash_code, unsigned> Cache;
   FileDistanceOptions Opts;
 };
 
 // Supports lookups like FileDistance, but the lookup keys are URIs.
 // We convert each of the sources to the scheme of the URI and do a FileDistance
 // comparison on the bodies.
 class URIDistance {
 public:
+  // \p Sources must contain absolute paths, not URIs.
   URIDistance(llvm::StringMap<SourceParams> Sources,
               const FileDistanceOptions &Opts = {})
       : Sources(Sources), Opts(Opts) {}
 
   // Computes the minimum distance from any source to the URI.
   // Only sources that can be mapped into the URI's scheme are considered.
   unsigned distance(llvm::StringRef URI);