fill all nef, manifest, debugInfo docs (#1271)

* fill all nef, manifest, debugInfo docs

* More docs about params

src/Neo.Compiler.CSharp/Optimizer/Analysers/BasicBlock.cs

@@ -167,7 +167,7 @@ public HashSet<BasicBlock> BlocksCoveredFromAddr(int entryAddr, bool includeCall
         /// <summary>
         /// Get the set of addresses covered by the input set of BasicBlocks
         /// </summary>
-        /// <param name="blocks"></param>
+        /// <param name="blocks">Basic blocks that composes the whole contract</param>
         /// <returns></returns>
         public static HashSet<int> AddrCoveredByBlocks(IEnumerable<BasicBlock> blocks)
         {

src/Neo.Compiler.CSharp/Optimizer/Analysers/InstructionCoverage.cs

@@ -189,8 +189,9 @@ public BranchType HandleAbort(int entranceAddr, int abortFromAddr, Stack<TryStat
         /// Cover a basic block, and recursively cover all branches
         /// </summary>
         /// <param name="addr">Starting address of script. Should start at a basic block</param>
-        /// <param name="script"></param>
-        /// <param name="coveredMap"></param>
+        /// <param name="tryStack">try-catch-finally stack</param>
+        /// <param name="continueFromBasicBlockEntranceAddr">Specify the previous basic block entrance address, if we continue execution from the previous basic block</param>
+        /// <param name="jumpFromBasicBlockEntranceAddr">Specify the entrance address of the basic block as the source of jump, if we jumped to current address from that basic block</param>
         /// <returns>Whether it is possible to return without exception</returns>
         /// <exception cref="BadScriptException"></exception>
         /// <exception cref="NotImplementedException"></exception>

src/Neo.Compiler.CSharp/Optimizer/Analysers/JumpTarget.cs

@@ -96,7 +96,7 @@ public static (
         public static (
             Dictionary<Instruction, Instruction>,  // jump source to target
             Dictionary<Instruction, (Instruction, Instruction)>,  // try source to targets
-            Dictionary<Instruction, HashSet<Instruction>>  // target to source
+            Dictionary<Instruction, HashSet<Instruction>>  // all jump and try targets to sources
             )
             FindAllJumpAndTrySourceToTargets(List<(int, Instruction)> addressAndInstructionsList, bool includePUSHA = true)
         {

src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/AssetBuilder.cs

@@ -13,13 +13,14 @@ public static class AssetBuilder
         /// That means you should get the Instructions from the same initial source.
         /// Do not script.EnumerateInstructions for many times.
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <param name="simplifiedInstructionsToAddress">new Instruction => int address</param>
-        /// <param name="jumpSourceToTargets"></param>
-        /// <param name="trySourceToTargets"></param>
-        /// <param name="oldAddressToInstruction"></param>
+        /// <param name="jumpSourceToTargets">All jumping instructions source => target</param>
+        /// <param name="trySourceToTargets">All try instructions source => target</param>
+        /// <param name="oldAddressToInstruction">old int address => Instruction</param>
+        /// <param name="oldSequencePointAddressToNew">old int address => new int address</param>
         /// <returns></returns>
         public static (NefFile, ContractManifest, JObject?) BuildOptimizedAssets(
             NefFile nef, ContractManifest manifest, JObject? debugInfo,

src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/DebugInfoBuilder.cs

@@ -14,9 +14,10 @@ static class DebugInfoBuilder
         /// <summary>
         /// Modify debug info to fit simplified instructions
         /// </summary>
-        /// <param name="debugInfo"></param>
+        /// <param name="debugInfo">Debug information</param>
         /// <param name="simplifiedInstructionsToAddress">new Instruction => int address</param>
-        /// <param name="oldAddressToInstruction"></param>
+        /// <param name="oldAddressToInstruction">old int address => Instruction</param>
+        /// <param name="oldSequencePointAddressToNew">old int address => new int address</param>
         /// <returns></returns>
         public static JObject? ModifyDebugInfo(JObject? debugInfo,
             System.Collections.Specialized.OrderedDictionary simplifiedInstructionsToAddress,

src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/OptimizedScriptBuilder.cs

@@ -14,8 +14,8 @@ static class OptimizedScriptBuilder
         /// Build script with instruction dictionary and jump
         /// </summary>
         /// <param name="simplifiedInstructionsToAddress">new Instruction => int address</param>
-        /// <param name="jumpSourceToTargets"></param>
-        /// <param name="trySourceToTargets"></param>
+        /// <param name="jumpSourceToTargets">All jumping instructions source => target</param>
+        /// <param name="trySourceToTargets">All try instructions source => target</param>
         /// <param name="oldAddressToInstruction">Used for convenient debugging only</param>
         /// <returns></returns>
         /// <exception cref="BadScriptException"></exception>
@@ -84,11 +84,11 @@ public static Script BuildScriptWithJumpTargets(
         /// Typically used when you delete the oldTarget from script
         /// and the newTarget is the first following instruction undeleted in script
         /// </summary>
-        /// <param name="oldTarget"></param>
-        /// <param name="newTarget"></param>
-        /// <param name="jumpSourceToTargets"></param>
-        /// <param name="jumpTargetToSources"></param>
-        /// <param name="trySourceToTargets"></param>
+        /// <param name="oldTarget">target instruction in the old script</param>
+        /// <param name="newTarget">target instruction in the new script</param>
+        /// <param name="jumpSourceToTargets">All jumping instructions source => target</param>
+        /// <param name="trySourceToTargets">All try instructions source => target</param>
+        /// <param name="jumpTargetToSources">All target instructions that are targets of jumps and trys</param>
         public static void RetargetJump(Instruction oldTarget, Instruction newTarget,
             Dictionary<Instruction, Instruction> jumpSourceToTargets,
             Dictionary<Instruction, (Instruction, Instruction)> trySourceToTargets,

src/Neo.Compiler.CSharp/Optimizer/Strategies/JumpCompresser.cs

@@ -26,9 +26,9 @@ public static class JumpCompresser
         /// <summary>
         /// A preparation for operations that may increase contract size.
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         /// [Strategy(Priority = int.MinValue)]  // No attribute
         public static (NefFile, ContractManifest, JObject?) UncompressJump(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -111,9 +111,9 @@ public static (NefFile, ContractManifest, JObject?) UncompressJump(NefFile nef,
         /// <summary>
         /// Compress _L instructions to short version, if possible
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = int.MinValue)]
         public static (NefFile, ContractManifest, JObject?) CompressJump(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -242,9 +242,9 @@ public static (NefFile, ContractManifest, JObject?) CompressJump(NefFile nef, Co
         /// If the removed JMP or JMP_L itself is a jump target,
         /// re-target to the instruction after the JMP or JMP_L
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = int.MaxValue)]
         public static (NefFile, ContractManifest, JObject?) RemoveUnnecessaryJumps(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -311,9 +311,9 @@ public static (NefFile, ContractManifest, JObject?) RemoveUnnecessaryJumps(NefFi
         /// <summary>
         /// If a JMP or JMP_L jumps to a RET, replace the JMP with RET
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = int.MaxValue - 4)]
         public static (NefFile, ContractManifest, JObject?) ReplaceJumpWithRet(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -369,9 +369,9 @@ public static (NefFile, ContractManifest, JObject?) ReplaceJumpWithRet(NefFile n
         /// If an unconditional jump targets a conditional jump, DO NOT replace the unconditional jump with a conditional jump to its final destination. THIS IS WRONG.
         /// This should be executed very early, before <see cref="Reachability.RemoveUncoveredInstructions"/>
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = int.MaxValue - 8)]
         public static (NefFile, ContractManifest, JObject?) FoldJump(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)

src/Neo.Compiler.CSharp/Optimizer/Strategies/Miscellaneous.cs

@@ -13,9 +13,9 @@ public static class Miscellaneous
         /// <summary>
         /// If any method token in nef is not utilized by CALLT, remove the method token.
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = int.MinValue)]
         public static (NefFile, ContractManifest, JObject?) RemoveMethodToken(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)

src/Neo.Compiler.CSharp/Optimizer/Strategies/Peephole.cs

@@ -35,9 +35,9 @@ public static class Peephole
         /// But at runtime we just need PUSH1 STLOC:$index_of_a
         /// TODO in the future: use symbolic VM to judge multiple instructions between DUP and DROP
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 10)]
         public static (NefFile, ContractManifest, JObject?) RemoveDupDrop(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -96,9 +96,9 @@ public static (NefFile, ContractManifest, JObject?) RemoveDupDrop(NefFile nef, C
         /// Do not replace PUSH0 EQUAL with NOT, because it cannot handle null
         /// Do not replace PUSH0 NOTEQUAL with NZ, because it cannot handle null
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 9)]
         public static (NefFile, ContractManifest, JObject?) UseNz(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -179,9 +179,9 @@ public static (NefFile, ContractManifest, JObject?) UseNz(NefFile nef, ContractM
         /// PUSHNULL EQUAL -> ISNULL
         /// PUSHNULL NOTEQUAL -> ISNULL NOT
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 9)]
         public static (NefFile, ContractManifest, JObject?) UseIsNull(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -260,9 +260,9 @@ public static (NefFile, ContractManifest, JObject?) UseIsNull(NefFile nef, Contr
         /// EQUAL NOT -> NOTEQUAL
         /// NOTEQUAL NOT -> EQUAL
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 10)]
         public static (NefFile, ContractManifest, JObject?) FoldNotInEqual(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -329,9 +329,9 @@ public static (NefFile, ContractManifest, JObject?) FoldNotInEqual(NefFile nef,
         /// NZ JMPIF -> JMPIF  // not applied, because NZ for null throws exception
         /// NOT JMPIFNOT -> JMPIF
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 8)]
         public static (NefFile, ContractManifest, JObject?) FoldNotInJmp(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -412,9 +412,9 @@ public static (NefFile, ContractManifest, JObject?) FoldNotInJmp(NefFile nef, Co
         /// and replace LDSFLD with PUSH const.
         /// This may increase contract size.
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 5)]
         public static (NefFile, ContractManifest, JObject?) InitStaticToConst(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)
@@ -588,9 +588,9 @@ public static (NefFile, ContractManifest, JObject?) InitStaticToConst(NefFile ne
         /// <summary>
         /// Delete unnecessary _initialize method
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         [Strategy(Priority = 1 << 5)]
         public static (NefFile, ContractManifest, JObject?) RemoveInitialize(NefFile nef, ContractManifest manifest, JObject? debugInfo = null)

src/Neo.Compiler.CSharp/Optimizer/Strategies/Reachability.cs

@@ -74,9 +74,9 @@ public static Dictionary<int, BranchType>
         /// <summary>
         /// RET RET -> RET
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns></returns>
         /// <exception cref="BadScriptException"></exception>
         [Strategy(Priority = int.MaxValue - 16)]

src/Neo.Compiler.CSharp/SecurityAnalyzer/CheckWitnessAnalyzer.cs

@@ -46,9 +46,9 @@ public string GetWarningInfo(bool print = false)
         /// <summary>
         /// 
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         public static CheckWitnessVulnerability AnalyzeCheckWitness
             (NefFile nef, ContractManifest manifest, JToken? debugInfo = null)
         {

src/Neo.Compiler.CSharp/SecurityAnalyzer/ReEntrancyAnalyzer.cs

@@ -67,9 +67,9 @@ public string GetWarningInfo(bool print = false)
         /// then B calls another contract C, changing the storage of C,
         /// finally you call C.
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         public static ReEntrancyVulnerabilityPair AnalyzeSingleContractReEntrancy
             (NefFile nef, ContractManifest manifest, JToken? debugInfo = null)
         {

src/Neo.Compiler.CSharp/SecurityAnalyzer/UpdateAnalyzer.cs

@@ -16,7 +16,7 @@ public static class UpdateAnalzyer
         /// </summary>
         /// <param name="nef">Nef file</param>
         /// <param name="manifest">Manifest</param>
-        /// <param name="debugInfo">Debug infromation</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns>whether it is possible to update the contract. May be wrong.</returns>
         public static bool AnalyzeUpdate
             (NefFile nef, ContractManifest manifest, JToken? debugInfo = null)

src/Neo.Compiler.CSharp/SecurityAnalyzer/WriteInTryAnalyzer.cs

@@ -58,9 +58,9 @@ public string GetWarningInfo(bool print = false)
         /// But it is ambiguous whether a write in try is actually reverted.
         /// You can still abort or throw exception when you catch an exception from try. This is safe.
         /// </summary>
-        /// <param name="nef"></param>
-        /// <param name="manifest"></param>
-        /// <param name="debugInfo"></param>
+        /// <param name="nef">Nef file</param>
+        /// <param name="manifest">Manifest</param>
+        /// <param name="debugInfo">Debug information</param>
         /// <returns>list of addresses that write in try</returns>
         public static WriteInTryVulnerability AnalyzeWriteInTry
             (NefFile nef, ContractManifest manifest, JToken? debugInfo = null)