Improve FileRegionsCache testability

src/Sarif/FileRegionsCache.cs

@@ -18,6 +18,18 @@ public class FileRegionsCache
  private readonly IFileSystem _fileSystem;
  private readonly Cache<string, Tuple<string, NewLineIndex>> _cache;
 
+ /// <summary>
+ /// Creates a new <see cref="FileRegionsCache"/> object.
+ /// </summary>
+ /// <param name="run">
+ /// The <see cref="Run"/> object whose data is to be cached.
+ /// </param>
+ /// <param name="capacity">
+ /// The initial capacity of the cache.
+ /// </param>
+ /// <param name="fileSystem">
+ /// An object that provides access to file system services.
+ /// </param>
  public FileRegionsCache(Run run, int capacity = DefaultCacheCapacity, IFileSystem fileSystem = null)
  {
  // Each file regions cache is associated with a single SARIF run.
@@ -28,20 +40,32 @@ public FileRegionsCache(Run run, int capacity = DefaultCacheCapacity, IFileSyste
  _fileSystem = fileSystem ?? FileSystem.Instance;
 
  // Build a cache for this data, with the load method it should use to add new entries
- _cache = new Cache<string, Tuple<string, NewLineIndex>>(BuildIndexForFile);
+ _cache = new Cache<string, Tuple<string, NewLineIndex>>(BuildIndexForFile, capacity);
  }
 
  /// <summary>
- /// Accepts a physical location and returns a Region object, based on the input
- /// physicalLocation.region property, that has all its properties populated. If an 
- /// input text region, for example, only specifies the startLine property, the returned
- /// Region instance will have computed and populated other properties, such as charOffset,
- /// charLength, etc. 
+ /// Creates a <see cref="Region"/> object, based on an existing Region, in which all
+ /// text-related properties have been populated.
  /// </summary>
- /// <param name="physicalLocation">The physical location containing the region which should be populated.</param>
- /// <param name="populateSnippet">Specifies whether the physicalLocation.region.snippet property should be populated.</param>
- /// <returns></returns>
- public Region PopulateTextRegionProperties(Region inputRegion, Uri uri, bool populateSnippet)
+ /// <remarks>
+ /// For example, if the input Region specifies only the StartLine property, the returned
+ /// Region instance will have computed and populated other text-related properties, such
+ /// as properties, such as CharOffset, CharLength, etc.
+ /// </remarks>
+ /// <param name="inputRegion">
+ /// Region object that forms the basis of the returned Region object.
+ /// </param>
+ /// <param name="uri">
+ /// URI of the artifact in which <paramref name="inputRegion"/> lies, used to retrieve
+ /// from the cache the location of each newline in the artifact.
+ /// </param>
+ /// <param name="populateSnippet">
+ /// Boolean that indicates if the region's Snippet property will be populated.
+ /// </param>
+ /// <returns>
+ /// A Region object whose text-related properties have been fully populated.
+ /// </returns>
+ public virtual Region PopulateTextRegionProperties(Region inputRegion, Uri uri, bool populateSnippet)
  {
  if (inputRegion == null || inputRegion.IsBinaryRegion)
  {