Add docs for CilTools.Visualization

CilTools.Visualization/CilTools.Visualization.csproj

@@ -2,7 +2,9 @@
 
  <PropertyGroup>
  <TargetFrameworks>netstandard2.0;net45</TargetFrameworks>
- <Description>Provides APIs that visualize syntax trees as HTML</Description>
+ <GenerateDocumentationFile>true</GenerateDocumentationFile>
+ <PackageLicenseFile>license.txt</PackageLicenseFile>
+ <Description>Provides APIs that visualize syntax trees</Description>
  <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  <PackageTags>dotnet dotnet-standard dotnet-framework syntax html visualization</PackageTags>
  <PackageIcon>IL.png</PackageIcon>
@@ -18,6 +20,10 @@
  <Pack>True</Pack>
  <PackagePath></PackagePath>
  </None>
+ <None Include="license.txt">
+ <Pack>True</Pack>
+ <PackagePath></PackagePath>
+ </None>
  </ItemGroup>
 
 </Project>

CilTools.Visualization/HtmlVisualizer.cs

@@ -33,6 +33,9 @@ public void AddUrlProvider(UrlProviderBase provider)
  this._urlProviders.Add(provider);
  }
 
+ /// <summary>
+ /// Removes all custom URL providers from this generator
+ /// </summary>
  public void RemoveAllProviders()
  {
  this._urlProviders.Clear();
@@ -181,6 +184,7 @@ static string GetInstructionAnchor(CilInstruction instr)
  return GetInstructionAnchor(instr.Method, instr.ByteOffset);
  }
 
+ /// <inheritdoc/>
  public override void RenderNode(SyntaxNode node, VisualizationOptions options, TextWriter target)
  {
  if (options == null) options = new VisualizationOptions();
@@ -319,18 +323,21 @@ public override void RenderNode(SyntaxNode node, VisualizationOptions options, T
  }
  }
 
+ /// <inheritdoc/>
  public override void RenderParagraph(string content, TextWriter target)
  {
  target.Write("<p>");
  target.Write(WebUtility.HtmlEncode(content));
  target.WriteLine("</p>");
  }
 
+ /// <inheritdoc/>
  protected override void StartBlock(VisualizationOptions options, TextWriter target)
  {
  target.Write("<pre style=\"white-space: pre-wrap;\"><code>");
  }
 
+ /// <inheritdoc/>
  protected override void EndBlock(VisualizationOptions options, TextWriter target)
  {
  target.Write("</code></pre>");

CilTools.Visualization/OutputFormat.cs

@@ -7,8 +7,24 @@
 
 namespace CilTools.Visualization
 {
+ /// <summary>
+ /// Specifies visualization output format
+ /// </summary>
  public enum OutputFormat
  {
- Html = 1, Plaintext = 2, ConsoleText = 3
+ /// <summary>
+ /// Hypertext Markup Language (HTML) format
+ /// </summary>
+ Html = 1, 
+
+ /// <summary>
+ /// Plain text format
+ /// </summary>
+ Plaintext = 2,
+
+ /// <summary>
+ /// Text printed into console (with colors)
+ /// </summary>
+ ConsoleText = 3
  }
 }

CilTools.Visualization/SyntaxVisualizer.cs

@@ -79,6 +79,9 @@ public string RenderToString(IEnumerable<SyntaxNode> nodes)
  return this.RenderToString(nodes, new VisualizationOptions());
  }
 
+ /// <summary>
+ /// Creates a new instance of the visualizer for the specified output format
+ /// </summary>
  public static SyntaxVisualizer Create(OutputFormat fmt)
  {
  switch (fmt)

CilTools.Visualization/VisualizationOptions.cs

@@ -14,11 +14,17 @@ public class VisualizationOptions
  {
  Dictionary<string, object> _dict = new Dictionary<string, object>();
 
+ /// <summary>
+ /// Creates a new instance of the visualization options with default option values
+ /// </summary>
  public VisualizationOptions()
  {
  this.EnableSyntaxHighlighting = true;
  }
 
+ /// <summary>
+ /// Gets the value of the option with the specified name, or <c>null</c> if the option is not set.
+ /// </summary>
  public object GetOption(string name)
  {
  object val;
@@ -27,11 +33,21 @@ public object GetOption(string name)
  else return null;
  }
 
+ /// <summary>
+ /// Sets the value for the specified option
+ /// </summary>
  public void SetOption(string name, object val)
  {
  this._dict[name] = val;
  }
 
+ /// <summary>
+ /// Gets or sets the offset of the first highlighted instruction, in bytes
+ /// </summary>
+ /// <remarks>
+ /// If the instruction highlighting is not used, should be set to -1. This property is only honoured by HTML 
+ /// visualizer.The default value is -1.
+ /// </remarks>
  public int HighlightingStartOffset
  {
  get
@@ -45,6 +61,13 @@ public int HighlightingStartOffset
  set { this.SetOption("HighlightingStartOffset", value); }
  }
 
+ /// <summary>
+ /// Gets or sets the offset of the last highlighted instruction, in bytes
+ /// </summary>
+ /// <remarks>
+ /// If the instruction highlighting is not used, should be set to -1. This property is only honoured by HTML 
+ /// visualizer.The default value is -1.
+ /// </remarks>
  public int HighlightingEndOffset
  {
  get
@@ -80,6 +103,13 @@ internal bool EnableMethodDefinitionLinks
  }
  }
 
+ /// <summary>
+ /// Gets or sets the boolean value indicating whether the instruction navigation hyperlinks are enabled
+ /// </summary>
+ /// <remarks>
+ /// When this property is set to <c>true</c>, labels in jump instructions are rendered as hyperlinks to 
+ /// the target instruction. This property is only honoured by HTML visualizer. The default value is <c>false</c>.
+ /// </remarks>
  public bool EnableInstructionNavigation
  {
  get

CilTools.Visualization/license.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, SmallSoft (https://gitflic.ru/user/smallsoft)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docfx_project/docfx.json

@@ -17,6 +17,10 @@
  {
  "files": ["CilTools.SourceCode.dll"], 
  "src": "../CilTools.SourceCode/bin/Debug/net35"
+ },
+ {
+ "files": ["CilTools.Visualization.dll"],
+ "src": "../CilTools.Visualization/bin/Debug/net45"
  }
  ],
  "dest": "api",

scripts/package.ps1

@@ -19,6 +19,7 @@ $fileList = "CilTools.BytecodeAnalysis.dll",
  "CilTools.SourceCode.dll",
  "CilTools.SourceCode.xml",
  "CilTools.Visualization.dll",
+ "CilTools.Visualization.xml",
  "CilView.exe",
  "CilView.exe.config",
  "CilView.Core.dll",

scripts/package_cli.ps1

@@ -19,6 +19,7 @@ $fileList = "CilTools.BytecodeAnalysis.dll",
  "CilTools.SourceCode.dll",
  "CilTools.SourceCode.xml",
  "CilTools.Visualization.dll",
+ "CilTools.Visualization.xml",
  "CilView.Core.dll",
  "cil.dll",
  "cil.runtimeconfig.json",