Maintenance: doc comments, public fields => properties.

src/Core/Analysis/SsaState.cs

@@ -55,7 +55,9 @@ public SsaState(Procedure proc)
         /// <paramref name="stmts"/> statement list, or -1 if there was none.
         /// </summary>
         /// <param name="stmts"></param>
-        /// <returns></returns>
+        /// <returns>The index of the last <see cref="DefInstruction"/>
+        /// or -1 if there is none.
+        /// </returns>
         private static int LastDefPosition(StatementList stmts)
         {
             for (int i = stmts.Count - 1; i >= 0; --i)
@@ -112,7 +114,7 @@ public void Dump(bool trace)
 		}
 
         /// <summary>
-        /// Validates the SSA state for consistency. If found inconsisted, the <paramref name="error"/> 
+        /// Validates the SSA state for consistency. If found inconsistent, the <paramref name="error"/> 
         /// callback is called, passing an error message suitable for a Debug.Assert call.
         /// </summary>
         /// <param name="error">Callback for raising errors.</param>
@@ -284,9 +286,10 @@ public SsaIdentifier InsertAfterDefinition(Statement stmBefore, AliasAssignment
 
         /// <summary>
         /// Deletes a statement by removing all the ids it references 
-        /// from SSA state, then removes the statement itself from code.
+        /// from SSA state, then removes the statement itself from 
+        /// the <see cref="Block"/> it is contained in.
         /// </summary>
-        /// <param name="stm"></param>
+        /// <param name="stm">The <see cref="Statement"/> to delete.</param>
         public void DeleteStatement(Statement stm)
 		{
 			// Remove all definitions and uses.
@@ -303,7 +306,9 @@ public void DeleteStatement(Statement stm)
 		/// Writes all SSA identifiers, showing the original variable,
 		/// the defining statement, and the using statements.
 		/// </summary>
-		/// <param name="writer"></param>
+		/// <param name="writer"><see cref="TextWriter"/> into which the
+        /// formatted output is written.
+        /// </param>
 		public void Write(TextWriter writer)
 		{
 			foreach (SsaIdentifier id in Identifiers)

src/Core/Code/CallInstruction.cs

@@ -87,17 +87,17 @@ public class CallBinding
         /// The <see cref="Storage"/> used for an argument to a call. The storage
         /// is relative to the caller's frame.
         /// </summary>
-        public Storage Storage;
+        public Storage Storage { get; }
 
         /// <summary>
         /// The argument expression bound to a parameter of a call.
         /// </summary>
-        public Expression Expression;
+        public Expression Expression { get; set; }
 
         /// <summary>
         /// Argument bits used by the callee.
         /// </summary>
-        public BitRange BitRange;
+        public BitRange BitRange { get; }
 
         public CallBinding(Storage stg, Expression exp)
         {

src/Core/CodePatch.cs

@@ -19,9 +19,6 @@
 #endregion
 
 using Reko.Core.Rtl;
-using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Reko.Core
 {

src/Core/DynamicLinker.cs

@@ -38,6 +38,25 @@ namespace Reko.Core
     /// </summary>
     public interface IDynamicLinker
     {
+        /// <summary>
+        /// Find an external procedure, based on its name. The optional
+        /// <paramref name="moduleName"/> allows specifying a particular
+        /// code module hosting the external procedure.
+        /// </summary>
+        /// <param name="moduleName">
+        /// Optional name of the module hosting the externa procedure.
+        /// </param>
+        /// <param name="importName">
+        /// The name of the external procedure.
+        /// </param>
+        /// <param name="platform">
+        /// The operating environment hosting the executable program.
+        /// </param>
+        /// <returns>
+        /// If an external procedure matching <paramref name="importName"/>
+        /// and <paramref name="moduleName"/> can be located, it is returned,
+        /// otherwise null.
+        /// </returns>
         ExternalProcedure? ResolveProcedure(string? moduleName, string importName, IPlatform platform);
         ExternalProcedure? ResolveProcedure(string moduleName, int ordinal, IPlatform platform);
         Expression? ResolveImport(string? moduleName, string globalName, IPlatform platform);

src/Core/ExternalProcedure.cs

@@ -18,7 +18,6 @@
  */
 #endregion
 
-using Reko.Core.Code;
 using Reko.Core.Output;
 using Reko.Core.Serialization;
 using Reko.Core.Types;
@@ -29,7 +28,7 @@ namespace Reko.Core
 {
     /// <summary>
     /// Models a procedure in an external API, whose signature is known, but 
-    /// whose code is irrelevant to the decompilation.
+    /// whose code is not included in decompilation.
     /// </summary>
 	public class ExternalProcedure : ProcedureBase
 	{

src/Core/MetadataFile.cs

@@ -18,11 +18,7 @@
  */
 #endregion
 
-using System;
-using System.Collections.Generic;
 using System.ComponentModel;
-using System.Linq;
-using System.Text;
 
 namespace Reko.Core
 {

src/Core/ModuleDescriptor.cs

@@ -19,11 +19,8 @@
 #endregion
 
 using Reko.Core.Loading;
-using Reko.Core.Types;
-using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Text;
 
 namespace Reko.Core
 {

src/Core/Types/FunctionType.cs

@@ -19,9 +19,7 @@
 #endregion
 
 using Reko.Core.Expressions;
-using Reko.Core.Machine;
 using Reko.Core.Output;
-using Reko.Core.Serialization;
 using System;
 using System.Collections.Generic;
 using System.IO;

src/Core/Types/StructureField.cs

@@ -187,7 +187,7 @@ public void AddRange(IEnumerable<StructureField> fields)
         }
 
         /// <summary>
-        /// Returns the structurefield exactly located at the specified offset.
+        /// Returns the structure field exactly located at the specified offset.
         /// </summary>
         /// <param name="offset">Offset (in bytes) of the field to retrieve.</param>
         /// <returns>The requested StructureField if it exists at <paramref>offset</paramref>, otherwise null.</returns>

src/Core/Types/TypeGraphWriter.cs

@@ -19,10 +19,7 @@
 #endregion
 
 using Reko.Core.Output;
-using System;
 using System.Collections.Generic;
-using System.IO;
-using System.Text;
 
 namespace Reko.Core.Types
 {

src/Core/UserGlobal.cs

@@ -25,6 +25,9 @@
 
 namespace Reko.Core
 {
+    /// <summary>
+    /// Models a user-specified global varaible.
+    /// </summary>
     public class UserGlobal
     {
         public Address Address { get; set; }

src/Decompiler/Analysis/DataFlowAnalysis.cs

@@ -314,7 +314,7 @@ public SsaState RunAnalyses(IAnalysisFactory? analysisFactory, AnalysisContext c
         public void ClearTestFiles()
         {
             var testSvc = this.services.GetService<ITestGenerationService>();
-            if (testSvc != null)
+            if (testSvc is not null)
             {
                 testSvc.RemoveFiles("analysis_");
             }

src/Decompiler/Analysis/ProcedureFlow.cs

@@ -43,7 +43,7 @@ public class ProcedureFlow : DataFlow
         /// A collection of each storage that is live-in to the procedure,
         /// and the bits that are live in.
         /// </summary>
-        public Dictionary<Storage, BitRange> BitsUsed;
+        public Dictionary<Storage, BitRange> BitsUsed { get; set; }
 
         /// <summary>
         /// The data types inferred for each live-in storage.
@@ -65,23 +65,58 @@ public class ProcedureFlow : DataFlow
         /// </remarks>
         public Dictionary<Storage, LiveOutUse> BitsLiveOut { get; set; }
 
+        /// <summary>
+        /// A collection of all flag groups that are live-out after the 
+        /// procedure is called, grouped by the flag register in which
+        /// they are located.
+        /// </summary>
         public Dictionary<RegisterStorage, LiveOutFlagsUse> LiveOutFlags { get; set; }
 
-        public HashSet<Storage> Preserved;			// Registers explicitly preserved by the procedure.
-		public Dictionary<RegisterStorage, uint> grfPreserved;
+        /// <summary>
+        /// Registers explicitly preserved by the procedure.
+        /// </summary>
+        /// <remarks>
+        /// Registers are typically preserved when register values are pushed
+        /// to the stack at the entry of the procedure, and popped before 
+        /// leaving.
+        /// </remarks>
+        public HashSet<Storage> Preserved { get; }
+
+        /// <summary>
+        /// Flag bits explicitly preserved by the procedure, organized
+        /// by the status register in which they are stored.
+        /// </summary>
+        /// <remarks>
+        /// This typically occurs register values are pushed to the
+        /// stack at the entry of the procedure, and popped before 
+        /// leaving.
+        /// </remarks>
+		public Dictionary<RegisterStorage, uint> PreservedFlags { get; }
+
+        /// <summary>
+        /// Registers that have been modified at the end of the execution of
+        /// the <see cref="Procedure"/>.
+        /// </summary>
+        public HashSet<Storage> Trashed { get; }
+
+        /// <summary>
+        /// Condition code flags that have been modified at the end of the execution of
+        /// the <see cref="Procedure"/>, grouped by the status register they
+        /// are part of.
+        /// </summary>
+        public Dictionary<RegisterStorage, uint> grfTrashed { get; }
 
-		public Dictionary<RegisterStorage,uint> grfTrashed;
-		public HashSet<Storage> Trashed;        // Registers globally trashed by procedure and/or callees.
-
         /// <summary>
         /// If present, indicates a register always has a constant value
         /// leaving the procedure.
         /// </summary>
-        public Dictionary<Storage, Constant> Constants; 
+        public Dictionary<Storage, Constant> Constants { get; }
 
-        // True if calling this procedure terminates the thread/process. This implies
-        // that no code path reached the exit block without first terminating the process.
-        public bool TerminatesProcess;
+        /// <summary>
+        /// True if calling this procedure terminates the thread/process. This implies
+        /// that no code path reached the exit block without first terminating the process.
+        /// </summary>
+        public bool TerminatesProcess { get; set; }
 
         public ProcedureFlow(Procedure proc)
         {
@@ -92,7 +127,7 @@ public ProcedureFlow(Procedure proc)
             Constants = new Dictionary<Storage, Constant>();
 
             grfTrashed = new Dictionary<RegisterStorage, uint>();
-            grfPreserved = new Dictionary<RegisterStorage, uint>();
+            PreservedFlags = new Dictionary<RegisterStorage, uint>();
             LiveOutFlags = new Dictionary<RegisterStorage, LiveOutFlagsUse>();
 
             BitsLiveOut = new Dictionary<Storage, LiveOutUse>();
@@ -118,7 +153,7 @@ public override void Emit(IProcessorArchitecture arch, TextWriter writer)
 			writer.WriteLine();
 			EmitRegisters(arch, "// Trashed:", grfTrashed, Trashed, writer);
 			writer.WriteLine();
-			EmitRegisters(arch, "// Preserved:", grfPreserved, Preserved, writer);
+			EmitRegisters(arch, "// Preserved:", PreservedFlags, Preserved, writer);
 			writer.WriteLine();
             if (TerminatesProcess)
                 writer.WriteLine("// Terminates process");

src/Decompiler/Analysis/ProcedureGraph.cs

@@ -25,6 +25,10 @@
 
 namespace Reko.Analysis
 {
+    /// <summary>
+    /// This class is a wrapper for the <see cref="CallGraph"/> of a program.
+    /// The edges go from calling procedure to called procedure.
+    /// </summary>
     public class ProcedureGraph : DirectedGraph<Procedure>
     {
         private readonly CallGraph cg;

src/Decompiler/Analysis/StackPointerBackpropagator.cs

@@ -24,7 +24,6 @@
 using Reko.Core.Expressions;
 using Reko.Core.Operators;
 using Reko.Core.Services;
-using Reko.Services;
 using System;
 using System.Collections.Generic;
 using System.Linq;

src/Decompiler/Analysis/TrashedRegisterFinder.cs

@@ -576,17 +576,17 @@ public bool VisitUseInstruction(UseInstruction use)
                     var value = ctx.GetValue(id);
                     if (value is Identifier idV && idV == sid.OriginalIdentifier)
                     {
-                        ctx.ProcFlow.grfPreserved[grfStorage.FlagRegister] =
-                            ctx.ProcFlow.grfPreserved.Get(grfStorage.FlagRegister) | grfStorage.FlagGroupBits;
+                        ctx.ProcFlow.PreservedFlags[grfStorage.FlagRegister] =
+                            ctx.ProcFlow.PreservedFlags.Get(grfStorage.FlagRegister) | grfStorage.FlagGroupBits;
                         ctx.ProcFlow.grfTrashed[grfStorage.FlagRegister] =
                             ctx.ProcFlow.grfTrashed.Get(grfStorage.FlagRegister) & ~grfStorage.FlagGroupBits;
                     }
                     else
                     {
                         ctx.ProcFlow.grfTrashed[grfStorage.FlagRegister] =
                             ctx.ProcFlow.grfTrashed.Get(grfStorage.FlagRegister) | grfStorage.FlagGroupBits;
-                        ctx.ProcFlow.grfPreserved[grfStorage.FlagRegister] =
-                            ctx.ProcFlow.grfPreserved.Get(grfStorage.FlagRegister) & ~grfStorage.FlagGroupBits;
+                        ctx.ProcFlow.PreservedFlags[grfStorage.FlagRegister] =
+                            ctx.ProcFlow.PreservedFlags.Get(grfStorage.FlagRegister) & ~grfStorage.FlagGroupBits;
                     }
                     return true;
                 }

src/Decompiler/Analysis/UnSsaTransform.cs

@@ -22,11 +22,6 @@
 using Reko.Core.Analysis;
 using Reko.Core.Code;
 using Reko.Core.Expressions;
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Reko.Analysis
 {

src/Decompiler/Analysis/UnreachableBlockRemover.cs

@@ -24,7 +24,6 @@
 using Reko.Core.Expressions;
 using Reko.Core.Graphs;
 using Reko.Core.Services;
-using Reko.Services;
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Linq;

src/Decompiler/Analysis/UsedRegisterFinder.cs

@@ -157,9 +157,12 @@ storage is FlagGroupStorage ||
         /// <returns>The bit range used by sid</returns>
         public BitRange Classify(SsaIdentifier sid)
         {
+            var idPrev = idCur;
             idCur = sid.Identifier;
-            return sid.Uses
+            var result = sid.Uses
                 .Aggregate(BitRange.Empty, (w, stm) => w | stm.Instruction.Accept(this));
+            idCur = idPrev;
+            return result;
         }
 
         private DataType DataTypeOf(
@@ -231,27 +234,20 @@ public BitRange VisitAssignment(Assignment ass)
                 {
                     // A simple assignment a = b is a copy, and so we must chase
                     // the uses of a.
-                    var idOld = idCur;
-                    idCur = ass.Dst;
                     var n = Classify(ssa.Identifiers[ass.Dst]);
-                    idCur = idOld;
                     return n;
                 }
             case Slice slice:
                 {
                     // a = SLICE(a', b) is also a copy, so we must chase the uses of a'.
-                    var idOld = idCur;
                     var n = Classify(ssa.Identifiers[ass.Dst]);
                     n <<= slice.Offset;
-                    idCur = idOld;
                     return n;
                 }
             case MkSequence seq:
                 {
                     // First verify that we are indeed using the sequence.
-                    var idOld = idCur;
                     var n = Classify(ssa.Identifiers[ass.Dst]);
-                    idCur = idOld;
                     if (n.IsEmpty)
                         return n;
                     // Now check the elements of the sequence.
@@ -315,10 +311,8 @@ public BitRange VisitPhiAssignment(PhiAssignment phi)
             if (!visited.TryGetValue(phi, out BitRange value))
             {
                 visited[phi] = BitRange.Empty;
-                var idOld = this.idCur;
                 value = Classify(ssa!.Identifiers[phi.Dst]);
                 visited[phi] = value;
-                this.idCur = idOld;
             }
             return value;
         }