Make the IntermediateSection and IntermediateSymbol less mutable

6 files changed, 105 insertions, 39 deletions

diff --git a/src/WixToolset.Data/Intermediate.cs b/src/WixToolset.Data/Intermediate.cs
index f9d33839..05ffdbf6 100644
--- a/src/WixToolset.Data/Intermediate.cs
+++ b/src/WixToolset.Data/Intermediate.cs
@@ -47,7 +47,7 @@ namespace WixToolset.Data
         public string Id { get; }
 
         /// <summary>
-        /// Get the id for the intermediate.
+        /// Get the level of the intermediate.
         /// </summary>
         public string Level { get; private set; }
 
diff --git a/src/WixToolset.Data/IntermediateSection.cs b/src/WixToolset.Data/IntermediateSection.cs
index cd001d5c..86aa0c89 100644
--- a/src/WixToolset.Data/IntermediateSection.cs
+++ b/src/WixToolset.Data/IntermediateSection.cs
@@ -11,18 +11,22 @@ namespace WixToolset.Data
     /// </summary>
     public class IntermediateSection
     {
+        private readonly List<IntermediateSymbol> symbols;
+
         /// <summary>
         /// Creates a new section as part of an intermediate.
         /// </summary>
         /// <param name="id">Identifier for section.</param>
         /// <param name="type">Type of section.</param>
         /// <param name="codepage">Codepage for resulting database.</param>
-        public IntermediateSection(string id, SectionType type, int codepage)
+        /// <param name="compilationId">Optional compilation identifier</param>
+        public IntermediateSection(string id, SectionType type, int codepage, string compilationId = null)
         {
             this.Id = id;
             this.Type = type;
             this.Codepage = codepage;
-            this.Symbols = new List<IntermediateSymbol>();
+            this.CompilationId = compilationId;
+            this.symbols = new List<IntermediateSymbol>();
         }
 
         /// <summary>
@@ -41,22 +45,53 @@ namespace WixToolset.Data
         /// Gets the codepage for the section.
         /// </summary>
         /// <value>Codepage for the section.</value>
-        public int Codepage { get; set; }
+        public int Codepage { get; }
 
         /// <summary>
         /// Gets and sets the identifier of the compilation of the source file containing the section.
         /// </summary>
-        public string CompilationId { get; set; }
+        public string CompilationId { get; }
 
         /// <summary>
         /// Gets and sets the identifier of the library that combined the section.
         /// </summary>
-        public string LibraryId { get; set; }
+        public string LibraryId { get; private set; }
 
         /// <summary>
         /// Symbols in the section.
         /// </summary>
-        public IList<IntermediateSymbol> Symbols { get; }
+        public IReadOnlyCollection<IntermediateSymbol> Symbols => this.symbols;
+
+        /// <summary>
+        /// Adds a symbol to the section.
+        /// </summary>
+        /// <typeparam name="T">Type of IntermediateSymbol to add to the section.</typeparam>
+        /// <param name="symbol">Symbol to add to the section.</param>
+        /// <returns>Symbol added to the section.</returns>
+        public T AddSymbol<T>(T symbol) where T : IntermediateSymbol
+        {
+            this.symbols.Add(symbol);
+            return symbol;
+        }
+
+        /// <summary>
+        /// Assigns the section to a library.
+        /// </summary>
+        /// <param name="libraryId">Identifier of the library.</param>
+        public void AssignToLibrary(string libraryId)
+        {
+            this.LibraryId = libraryId;
+        }
+
+        /// <summary>
+        /// Removes a symbol from the section.
+        /// </summary>
+        /// <param name="symbol">Symbol to remove.</param>
+        /// <returns>True if the symbol was removed; otherwise false.</returns>
+        public bool RemoveSymbol(IntermediateSymbol symbol)
+        {
+            return this.symbols.Remove(symbol);
+        }
 
         /// <summary>
         /// Parse a section from the JSON data.
@@ -79,7 +114,7 @@ namespace WixToolset.Data
             foreach (JsonObject symbolJson in symbolsJson)
             {
                 var symbol = IntermediateSymbol.Deserialize(creator, baseUri, symbolJson);
-                section.Symbols.Add(symbol);
+                section.symbols.Add(symbol);
             }
 
             return section;
diff --git a/src/WixToolset.Data/IntermediateSectionExtensions.cs b/src/WixToolset.Data/IntermediateSectionExtensions.cs
deleted file mode 100644
index 80e64eaa..00000000
--- a/src/WixToolset.Data/IntermediateSectionExtensions.cs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
-
-namespace WixToolset.Data
-{
-    public static class IntermediateSectionExtensions
-    {
-        public static T AddSymbol<T>(this IntermediateSection section, T symbol)
-            where T : IntermediateSymbol
-        {
-            section.Symbols.Add(symbol);
-            return symbol;
-        }
-    }
-}
diff --git a/src/WixToolset.Data/IntermediateSymbol.cs b/src/WixToolset.Data/IntermediateSymbol.cs
index 408be37c..4be17094 100644
--- a/src/WixToolset.Data/IntermediateSymbol.cs
+++ b/src/WixToolset.Data/IntermediateSymbol.cs
@@ -6,15 +6,28 @@ namespace WixToolset.Data
     using System.Diagnostics;
     using SimpleJson;
 
+    /// <summary>
+    /// Intermediate symbol.
+    /// </summary>
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public class IntermediateSymbol
     {
         private object tags;
 
+        /// <summary>
+        /// Creates an intermediate symbol.
+        /// </summary>
+        /// <param name="definition">Symbol definition.</param>
         public IntermediateSymbol(IntermediateSymbolDefinition definition) : this(definition, null, null)
         {
         }
 
+        /// <summary>
+        /// Creates an intermediate symbol with source line number and identifier. 
+        /// </summary>
+        /// <param name="definition">Symbol definition.</param>
+        /// <param name="sourceLineNumber">Source line number.</param>
+        /// <param name="id">Symbol identifier.</param>
         public IntermediateSymbol(IntermediateSymbolDefinition definition, SourceLineNumber sourceLineNumber, Identifier id = null)
         {
             this.Definition = definition;
@@ -23,18 +36,40 @@ namespace WixToolset.Data
             this.Id = id;
         }
 
+        /// <summary>
+        /// Gets the symbol's definition.
+        /// </summary>
         public IntermediateSymbolDefinition Definition { get; }
 
+        /// <summary>
+        /// Gets the symbol's fields.
+        /// </summary>
         public IntermediateField[] Fields { get; }
 
-        public SourceLineNumber SourceLineNumbers { get; set; }
-
-        public Identifier Id { get; set; }
-
+        /// <summary>
+        /// Gets the optional source line number of the symbol.
+        /// </summary>
+        public SourceLineNumber SourceLineNumbers { get; internal set; }
+
+        /// <summary>
+        /// Gets the optional identifier for the symbol.
+        /// </summary>
+        public Identifier Id { get; internal set; }
+
+        /// <summary>
+        /// Direct access by index to the symbol's fields.
+        /// </summary>
+        /// <param name="index">Index of the field to access.</param>
+        /// <returns>Symbol's field.</returns>
         public IntermediateField this[int index] => this.Fields[index];
 
         private string DebuggerDisplay => $"{this.Definition?.Name} {this.Id?.Id}";
 
+        /// <summary>
+        /// Add a custom tag to the symbol.
+        /// </summary>
+        /// <param name="add">String tag to add to the symbol.</param>
+        /// <returns>True if the tag was added; otherwise false if th tag was already present.</returns>
         public bool AddTag(string add)
         {
             if (this.tags == null)
@@ -73,6 +108,11 @@ namespace WixToolset.Data
             return true;
         }
 
+        /// <summary>
+        /// Tests whether a symbol has a tag.
+        /// </summary>
+        /// <param name="has">String tag to find.</param>
+        /// <returns>True if the symbol has the tag; otherwise false.</returns>
         public bool HasTag(string has)
         {
             if (this.tags == null)
@@ -97,6 +137,11 @@ namespace WixToolset.Data
             return false;
         }
 
+        /// <summary>
+        /// Removes a tag from the symbol.
+        /// </summary>
+        /// <param name="remove">String tag to remove.</param>
+        /// <returns>True if the tag was removed; otherwise false if the tag was not present.</returns>
         public bool RemoveTag(string remove)
         {
             if (this.tags is string tag)
diff --git a/src/WixToolset.Data/IntermediateSymbolDefinition.cs b/src/WixToolset.Data/IntermediateSymbolDefinition.cs
index 102a9f5c..dc913704 100644
--- a/src/WixToolset.Data/IntermediateSymbolDefinition.cs
+++ b/src/WixToolset.Data/IntermediateSymbolDefinition.cs
@@ -48,11 +48,11 @@ namespace WixToolset.Data
 
         public IntermediateSymbol CreateSymbol(SourceLineNumber sourceLineNumber = null, Identifier id = null)
         {
-            var result = (this.StrongSymbolType == typeof(IntermediateSymbol)) ? (IntermediateSymbol)Activator.CreateInstance(this.StrongSymbolType, this) : (IntermediateSymbol)Activator.CreateInstance(this.StrongSymbolType);
-            result.SourceLineNumbers = sourceLineNumber;
-            result.Id = id;
+            var symbol = (this.StrongSymbolType == typeof(IntermediateSymbol)) ? (IntermediateSymbol)Activator.CreateInstance(this.StrongSymbolType, this) : (IntermediateSymbol)Activator.CreateInstance(this.StrongSymbolType);
+            symbol.SourceLineNumbers = sourceLineNumber;
+            symbol.Id = id;
 
-            return result;
+            return symbol;
         }
 
         public bool AddTag(string add)
diff --git a/src/test/WixToolsetTest.Data/SerializeFixture.cs b/src/test/WixToolsetTest.Data/SerializeFixture.cs
index 56d08bc9..ff39cb33 100644
--- a/src/test/WixToolsetTest.Data/SerializeFixture.cs
+++ b/src/test/WixToolsetTest.Data/SerializeFixture.cs
@@ -22,7 +22,7 @@ namespace WixToolsetTest.Data
 
             var section = new IntermediateSection("test", SectionType.Product, 65001);
 
-            section.Symbols.Add(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "TestComponent"))
+            section.AddSymbol(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "TestComponent"))
             {
                 ComponentId = new Guid(1, 0, 0, new byte[8]).ToString("B"),
                 DirectoryRef = "TestFolder",
@@ -64,7 +64,7 @@ namespace WixToolsetTest.Data
             var sln = new SourceLineNumber("test.wxs", 1);
             var section = new IntermediateSection("test", SectionType.Product, 65001);
 
-            section.Symbols.Add(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "TestComponent"))
+            section.AddSymbol(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "TestComponent"))
             {
                 ComponentId = new Guid(1, 0, 0, new byte[8]).ToString("B"),
                 DirectoryRef = "TestFolder",
@@ -91,7 +91,7 @@ namespace WixToolsetTest.Data
 
                     wixout.Reopen(writable: true);
 
-                    section.Symbols.Add(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "NewComponent"))
+                    section.AddSymbol(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "NewComponent"))
                     {
                         ComponentId = new Guid(1, 0, 0, new byte[8]).ToString("B"),
                     });
@@ -135,7 +135,7 @@ namespace WixToolsetTest.Data
             symbol.Set(1, 2);
             symbol.Set(2, true);
 
-            section.Symbols.Add(symbol);
+            section.AddSymbol(symbol);
 
             var intermediate = new Intermediate("TestIntermediate", new[] { section }, null);
 
@@ -179,7 +179,7 @@ namespace WixToolsetTest.Data
             symbol.Set(2, true);
 
             var section = new IntermediateSection("test", SectionType.Product, 65001);
-            section.Symbols.Add(symbol);
+            section.AddSymbol(symbol);
 
             var intermediate1 = new Intermediate("TestIntermediate", new[] { section }, null);
 
@@ -201,7 +201,7 @@ namespace WixToolsetTest.Data
             symbol2.Set(3, "baz");
 
             var section2 = new IntermediateSection("test2", SectionType.Fragment, 65001);
-            section2.Symbols.Add(symbol2);
+            section2.AddSymbol(symbol2);
 
             var intermediate2 = new Intermediate("TestIntermediate2", new[] { section2 }, null);
 
@@ -262,7 +262,7 @@ namespace WixToolsetTest.Data
             symbol.AddTag("symbol1tag");
 
             var section = new IntermediateSection("test", SectionType.Product, 65001);
-            section.Symbols.Add(symbol);
+            section.AddSymbol(symbol);
 
             var intermediate1 = new Intermediate("TestIntermediate", new[] { section }, null);
 
@@ -290,7 +290,7 @@ namespace WixToolsetTest.Data
             symbol2.AddTag("symbol2tag2");
 
             var section2 = new IntermediateSection("test2", SectionType.Fragment, 65001);
-            section2.Symbols.Add(symbol2);
+            section2.AddSymbol(symbol2);
 
             var intermediate2 = new Intermediate("TestIntermediate2", new[] { section2 }, null);
 
@@ -356,7 +356,7 @@ namespace WixToolsetTest.Data
 
             var section = new IntermediateSection("test", SectionType.Product, 65001);
 
-            section.Symbols.Add(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "TestComponent"))
+            section.AddSymbol(new ComponentSymbol(sln, new Identifier(AccessModifier.Global, "TestComponent"))
             {
                 ComponentId = new Guid(1, 0, 0, new byte[8]).ToString("B"),
                 DirectoryRef = "TestFolder",