From a4c7643523a3fc79c2a79292d22487196ea388fb Mon Sep 17 00:00:00 2001
From: Rob Mensching <rob@firegiant.com>
Date: Mon, 19 Apr 2021 16:09:46 -0700
Subject: Prefer IReadOnlyCollection<> or IReadOnlyList<> over IEnumerable<>

Part of wixtoolset/issues#6422
---
 src/WixToolset.Extensibility/Data/IBindContext.cs  | 12 ++++----
 src/WixToolset.Extensibility/Data/IBindResult.cs   | 17 ++++++++--
 .../Data/ICompileContext.cs                        |  2 +-
 .../Data/IDecompileContext.cs                      |  2 +-
 .../Data/IDecompileResult.cs                       |  2 +-
 .../Data/ILayoutContext.cs                         |  6 ++--
 .../Data/ILibraryContext.cs                        | 36 +++++++++++++++++++---
 src/WixToolset.Extensibility/Data/ILinkContext.cs  | 31 ++++++++++++++++---
 .../Data/IPreprocessContext.cs                     | 29 +++++++++++++++--
 .../Data/IPreprocessResult.cs                      | 12 ++++++--
 .../Data/IResolveContext.cs                        | 10 +++---
 .../Data/IResolveFileResult.cs                     | 12 ++++++--
 .../Data/IResolveResult.cs                         |  4 +--
 13 files changed, 137 insertions(+), 38 deletions(-)

(limited to 'src/WixToolset.Extensibility/Data')

diff --git a/src/WixToolset.Extensibility/Data/IBindContext.cs b/src/WixToolset.Extensibility/Data/IBindContext.cs
index f1977c01..d0c65683 100644
--- a/src/WixToolset.Extensibility/Data/IBindContext.cs
+++ b/src/WixToolset.Extensibility/Data/IBindContext.cs
@@ -35,27 +35,27 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Delayed fields that need to be resolved again.
         /// </summary>
-        IEnumerable<IDelayedField> DelayedFields { get; set; }
+        IReadOnlyCollection<IDelayedField> DelayedFields { get; set; }
 
         /// <summary>
         /// Embedded files to extract.
         /// </summary>
-        IEnumerable<IExpectedExtractFile> ExpectedEmbeddedFiles { get; set; }
+        IReadOnlyCollection<IExpectedExtractFile> ExpectedEmbeddedFiles { get; set; }
 
         /// <summary>
         /// Binder extensions.
         /// </summary>
-        IEnumerable<IBinderExtension> Extensions { get; set; }
+        IReadOnlyCollection<IBinderExtension> Extensions { get; set; }
 
         /// <summary>
         /// File system extensions.
         /// </summary>
-        IEnumerable<IFileSystemExtension> FileSystemExtensions { get; set; }
+        IReadOnlyCollection<IFileSystemExtension> FileSystemExtensions { get; set; }
 
         /// <summary>
         /// Set of ICEs to execute.
         /// </summary>
-        IEnumerable<string> Ices { get; set; }
+        IReadOnlyCollection<string> Ices { get; set; }
 
         /// <summary>
         /// Intermedaite folder.
@@ -100,7 +100,7 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Set of ICEs to skip.
         /// </summary>
-        IEnumerable<string> SuppressIces { get; set; }
+        IReadOnlyCollection<string> SuppressIces { get; set; }
 
         /// <summary>
         /// Skip all ICEs.
diff --git a/src/WixToolset.Extensibility/Data/IBindResult.cs b/src/WixToolset.Extensibility/Data/IBindResult.cs
index 1654f24d..7fc52bd7 100644
--- a/src/WixToolset.Extensibility/Data/IBindResult.cs
+++ b/src/WixToolset.Extensibility/Data/IBindResult.cs
@@ -6,13 +6,24 @@ namespace WixToolset.Extensibility.Data
     using System.Collections.Generic;
     using WixToolset.Data;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Result of bind operation.
+    /// </summary>
     public interface IBindResult : IDisposable
     {
-        IEnumerable<IFileTransfer> FileTransfers { get; set; }
+        /// <summary>
+        /// Collection of file transfers to complete.
+        /// </summary>
+        IReadOnlyCollection<IFileTransfer> FileTransfers { get; set; }
 
-        IEnumerable<ITrackedFile> TrackedFiles { get; set; }
+        /// <summary>
+        /// Collection of files tracked during binding.
+        /// </summary>
+        IReadOnlyCollection<ITrackedFile> TrackedFiles { get; set; }
 
+        /// <summary>
+        /// Ouput of binding.
+        /// </summary>
         WixOutput Wixout { get; set; }
     }
 }
diff --git a/src/WixToolset.Extensibility/Data/ICompileContext.cs b/src/WixToolset.Extensibility/Data/ICompileContext.cs
index a86fee1a..2ee8f2a1 100644
--- a/src/WixToolset.Extensibility/Data/ICompileContext.cs
+++ b/src/WixToolset.Extensibility/Data/ICompileContext.cs
@@ -26,7 +26,7 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Set of extensions provided to the compiler.
         /// </summary>
-        IEnumerable<ICompilerExtension> Extensions { get; set; }
+        IReadOnlyCollection<ICompilerExtension> Extensions { get; set; }
 
         /// <summary>
         /// Gets or sets the platform which the compiler will use when defaulting 64-bit attributes and elements.
diff --git a/src/WixToolset.Extensibility/Data/IDecompileContext.cs b/src/WixToolset.Extensibility/Data/IDecompileContext.cs
index 63ed27d5..fe7d0465 100644
--- a/src/WixToolset.Extensibility/Data/IDecompileContext.cs
+++ b/src/WixToolset.Extensibility/Data/IDecompileContext.cs
@@ -16,7 +16,7 @@ namespace WixToolset.Extensibility.Data
 
         OutputType DecompileType { get; set; }
 
-        IEnumerable<IDecompilerExtension> Extensions { get; set; }
+        IReadOnlyCollection<IDecompilerExtension> Extensions { get; set; }
 
         string ExtractFolder { get; set; }
 
diff --git a/src/WixToolset.Extensibility/Data/IDecompileResult.cs b/src/WixToolset.Extensibility/Data/IDecompileResult.cs
index ad4d0841..cffd0976 100644
--- a/src/WixToolset.Extensibility/Data/IDecompileResult.cs
+++ b/src/WixToolset.Extensibility/Data/IDecompileResult.cs
@@ -11,7 +11,7 @@ namespace WixToolset.Extensibility.Data
     {
         XDocument Document { get; set; }
 
-        IEnumerable<string> ExtractedFilePaths { get; set; }
+        IReadOnlyCollection<string> ExtractedFilePaths { get; set; }
 
         Platform? Platform { get; set; }
     }
diff --git a/src/WixToolset.Extensibility/Data/ILayoutContext.cs b/src/WixToolset.Extensibility/Data/ILayoutContext.cs
index 3d49b877..b11b4d13 100644
--- a/src/WixToolset.Extensibility/Data/ILayoutContext.cs
+++ b/src/WixToolset.Extensibility/Data/ILayoutContext.cs
@@ -19,17 +19,17 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Extensions for use during layout.
         /// </summary>
-        IEnumerable<ILayoutExtension> Extensions { get; set; }
+        IReadOnlyCollection<ILayoutExtension> Extensions { get; set; }
 
         /// <summary>
         /// Set of tracked of files created during processing to be cleaned up.
         /// </summary>
-        IEnumerable<ITrackedFile> TrackedFiles { get; set; }
+        IReadOnlyCollection<ITrackedFile> TrackedFiles { get; set; }
 
         /// <summary>
         /// Set of files to transfer.
         /// </summary>
-        IEnumerable<IFileTransfer> FileTransfers { get; set; }
+        IReadOnlyCollection<IFileTransfer> FileTransfers { get; set; }
 
         /// <summary>
         /// File to capture list of content files.
diff --git a/src/WixToolset.Extensibility/Data/ILibraryContext.cs b/src/WixToolset.Extensibility/Data/ILibraryContext.cs
index d6359ffc..208b6f73 100644
--- a/src/WixToolset.Extensibility/Data/ILibraryContext.cs
+++ b/src/WixToolset.Extensibility/Data/ILibraryContext.cs
@@ -7,23 +7,49 @@ namespace WixToolset.Extensibility.Data
     using System.Threading;
     using WixToolset.Data;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Context provided during library creation operations.
+    /// </summary>
     public interface ILibraryContext
     {
+        /// <summary>
+        /// Service provider.
+        /// </summary>
         IServiceProvider ServiceProvider { get; }
 
+        /// <summary>
+        /// Indicates whether files should be bound into the library.
+        /// </summary>
         bool BindFiles { get; set; }
 
-        IEnumerable<IBindPath> BindPaths { get; set; }
+        /// <summary>
+        /// Collection of bindpaths used to bind files.
+        /// </summary>
+        IReadOnlyCollection<IBindPath> BindPaths { get; set; }
 
-        IEnumerable<ILibrarianExtension> Extensions { get; set; }
+        /// <summary>
+        /// Collection of extensions used during creation of library.
+        /// </summary>
+        IReadOnlyCollection<ILibrarianExtension> Extensions { get; set; }
 
+        /// <summary>
+        /// Identifier of the library.
+        /// </summary>
         string LibraryId { get; set; }
 
-        IEnumerable<Localization> Localizations { get; set; }
+        /// <summary>
+        /// Collection of localization files to use in the library.
+        /// </summary>
+        IReadOnlyCollection<Localization> Localizations { get; set; }
 
-        IEnumerable<Intermediate> Intermediates { get; set; }
+        /// <summary>
+        /// Collection of intermediates to include in the library.
+        /// </summary>
+        IReadOnlyCollection<Intermediate> Intermediates { get; set; }
 
+        /// <summary>
+        /// Cancellation token.
+        /// </summary>
         CancellationToken CancellationToken { get; set; }
     }
 }
diff --git a/src/WixToolset.Extensibility/Data/ILinkContext.cs b/src/WixToolset.Extensibility/Data/ILinkContext.cs
index 7524d18c..d56866f7 100644
--- a/src/WixToolset.Extensibility/Data/ILinkContext.cs
+++ b/src/WixToolset.Extensibility/Data/ILinkContext.cs
@@ -7,21 +7,44 @@ namespace WixToolset.Extensibility.Data
     using System.Threading;
     using WixToolset.Data;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Context provided during linking.
+    /// </summary>
     public interface ILinkContext
     {
+        /// <summary>
+        /// Service provider.
+        /// </summary>
         IServiceProvider ServiceProvider { get; }
 
-        IEnumerable<ILinkerExtension> Extensions { get; set; }
+        /// <summary>
+        /// Collection of extensions to use during linking.
+        /// </summary>
+        IReadOnlyCollection<ILinkerExtension> Extensions { get; set; }
 
-        IEnumerable<IExtensionData> ExtensionData { get; set; }
+        /// <summary>
+        /// Collection of extension data to use during linking.
+        /// </summary>
+        IReadOnlyCollection<IExtensionData> ExtensionData { get; set; }
 
+        /// <summary>
+        /// Expected output type.
+        /// </summary>
         OutputType ExpectedOutputType { get; set; }
 
-        IEnumerable<Intermediate> Intermediates { get; set; }
+        /// <summary>
+        /// Collection of intermediates to link.
+        /// </summary>
+        IReadOnlyCollection<Intermediate> Intermediates { get; set; }
 
+        /// <summary>
+        /// Symbol definition creator used to load extension data.
+        /// </summary>
         ISymbolDefinitionCreator SymbolDefinitionCreator { get; set; }
 
+        /// <summary>
+        /// Cancellation token.
+        /// </summary>
         CancellationToken CancellationToken { get; set; }
     }
 }
diff --git a/src/WixToolset.Extensibility/Data/IPreprocessContext.cs b/src/WixToolset.Extensibility/Data/IPreprocessContext.cs
index c6bdfe3a..69057c33 100644
--- a/src/WixToolset.Extensibility/Data/IPreprocessContext.cs
+++ b/src/WixToolset.Extensibility/Data/IPreprocessContext.cs
@@ -7,14 +7,25 @@ namespace WixToolset.Extensibility.Data
     using System.Threading;
     using WixToolset.Data;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Preprocessor context.
+    /// </summary>
     public interface IPreprocessContext
     {
+        /// <summary>
+        /// Service provider.
+        /// </summary>
         IServiceProvider ServiceProvider { get; }
 
-        IEnumerable<IPreprocessorExtension> Extensions { get; set; }
+        /// <summary>
+        /// Collection of extensions to use during preprocessing.
+        /// </summary>
+        IReadOnlyCollection<IPreprocessorExtension> Extensions { get; set; }
 
-        IEnumerable<string> IncludeSearchPaths { get; set; }
+        /// <summary>
+        /// Collection of search paths to find include files.
+        /// </summary>
+        IReadOnlyCollection<string> IncludeSearchPaths { get; set; }
 
         /// <summary>
         /// Gets the platform which the compiler will use when defaulting 64-bit attributes and elements.
@@ -22,12 +33,24 @@ namespace WixToolset.Extensibility.Data
         /// <value>The platform which the compiler will use when defaulting 64-bit attributes and elements.</value>
         Platform Platform { get; set; }
 
+        /// <summary>
+        /// Path to the source file being preprocessed.
+        /// </summary>
         string SourcePath { get; set; }
 
+        /// <summary>
+        /// Collection of name/value pairs used as preprocessor variables.
+        /// </summary>
         IDictionary<string, string> Variables { get; set; }
 
+        /// <summary>
+        /// Current source line number of the preprocessor.
+        /// </summary>
         SourceLineNumber CurrentSourceLineNumber { get; set; }
 
+        /// <summary>
+        /// Cancellation token.
+        /// </summary>
         CancellationToken CancellationToken { get; set; }
     }
 }
diff --git a/src/WixToolset.Extensibility/Data/IPreprocessResult.cs b/src/WixToolset.Extensibility/Data/IPreprocessResult.cs
index d46c8147..af224c1e 100644
--- a/src/WixToolset.Extensibility/Data/IPreprocessResult.cs
+++ b/src/WixToolset.Extensibility/Data/IPreprocessResult.cs
@@ -5,11 +5,19 @@ namespace WixToolset.Extensibility.Data
     using System.Collections.Generic;
     using System.Xml.Linq;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Result of preprocessing.
+    /// </summary>
     public interface IPreprocessResult
     {
+        /// <summary>
+        /// Document result of preprocessor.
+        /// </summary>
         XDocument Document { get; set; }
 
-        IEnumerable<IIncludedFile> IncludedFiles { get; set; }
+        /// <summary>
+        /// Collection of files included during preprocessing.
+        /// </summary>
+        IReadOnlyCollection<IIncludedFile> IncludedFiles { get; set; }
     }
 }
diff --git a/src/WixToolset.Extensibility/Data/IResolveContext.cs b/src/WixToolset.Extensibility/Data/IResolveContext.cs
index 6ab5b545..63159ccb 100644
--- a/src/WixToolset.Extensibility/Data/IResolveContext.cs
+++ b/src/WixToolset.Extensibility/Data/IResolveContext.cs
@@ -20,22 +20,22 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Bind paths used during resolution.
         /// </summary>
-        IEnumerable<IBindPath> BindPaths { get; set; }
+        IReadOnlyCollection<IBindPath> BindPaths { get; set; }
 
         /// <summary>
         /// Resolve extensions.
         /// </summary>
-        IEnumerable<IResolverExtension> Extensions { get; set; }
+        IReadOnlyCollection<IResolverExtension> Extensions { get; set; }
 
         /// <summary>
         /// Extension data.
         /// </summary>
-        IEnumerable<IExtensionData> ExtensionData { get; set; }
+        IReadOnlyCollection<IExtensionData> ExtensionData { get; set; }
 
         /// <summary>
         /// List of cultures to filter the localizations.
         /// </summary>
-        IEnumerable<string> FilterCultures { get; set; }
+        IReadOnlyCollection<string> FilterCultures { get; set; }
 
         /// <summary>
         /// Intermediate folder.
@@ -50,7 +50,7 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Localizations used to resolve.
         /// </summary>
-        IEnumerable<Localization> Localizations { get; set; }
+        IReadOnlyCollection<Localization> Localizations { get; set; }
 
         /// <summary>
         /// Indicates whether to allow localization and bind variables to remain unresolved.
diff --git a/src/WixToolset.Extensibility/Data/IResolveFileResult.cs b/src/WixToolset.Extensibility/Data/IResolveFileResult.cs
index c8dca81a..2f0df96c 100644
--- a/src/WixToolset.Extensibility/Data/IResolveFileResult.cs
+++ b/src/WixToolset.Extensibility/Data/IResolveFileResult.cs
@@ -4,11 +4,19 @@ namespace WixToolset.Extensibility.Data
 {
     using System.Collections.Generic;
 
-#pragma warning disable 1591 // TODO: add documentation
+    /// <summary>
+    /// Result of resolving a file.
+    /// </summary>
     public interface IResolveFileResult
     {
-        IEnumerable<string> CheckedPaths { get; set; }
+        /// <summary>
+        /// Collection of paths checked to find file.
+        /// </summary>
+        IReadOnlyCollection<string> CheckedPaths { get; set; }
 
+        /// <summary>
+        /// Path to found file, if found.
+        /// </summary>
         string Path { get; set; }
     }
 }
diff --git a/src/WixToolset.Extensibility/Data/IResolveResult.cs b/src/WixToolset.Extensibility/Data/IResolveResult.cs
index abffb415..0c5e0ccf 100644
--- a/src/WixToolset.Extensibility/Data/IResolveResult.cs
+++ b/src/WixToolset.Extensibility/Data/IResolveResult.cs
@@ -28,12 +28,12 @@ namespace WixToolset.Extensibility.Data
         /// <summary>
         /// Fields still requiring resolution.
         /// </summary>
-        IEnumerable<IDelayedField> DelayedFields { get; set; }
+        IReadOnlyCollection<IDelayedField> DelayedFields { get; set; }
 
         /// <summary>
         /// Files to extract from embedded .wixlibs.
         /// </summary>
-        IEnumerable<IExpectedExtractFile> ExpectedEmbeddedFiles { get; set; }
+        IReadOnlyCollection<IExpectedExtractFile> ExpectedEmbeddedFiles { get; set; }
 
         /// <summary>
         /// Resolved intermediate.
-- 
cgit v1.2.3-55-g6feb