Improve layout of API docs. Fix typos.

Washi1337 · May 13, 2023 · 2545e1a · 2545e1a
1 parent 48aadf6
commit 2545e1a
Show file tree

Hide file tree

Showing 45 changed files with 272 additions and 184 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -7,4 +7,5 @@
 /**/bin/
 /**/obj/
 _site/
-api/
+api/*/*.yml
+api/*/*.manifest
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,4 @@
+# AsmResolver API Reference
+
+This is the full API reference of the AsmResolver project.
+
diff --git a/docs/api/toc.yml b/docs/api/toc.yml
@@ -0,0 +1,12 @@
+- name: AsmResolver.dll
+  href: core/toc.yml
+- name: AsmResolver.PE.File.dll
+  href: pe-file/toc.yml
+- name: AsmResolver.PE.dll
+  href: pe/toc.yml
+- name: AsmResolver.PE.Win32Resources.dll
+  href: win32resources/toc.yml
+- name: AsmResolver.DotNet.dll
+  href: dotnet/toc.yml
+- name: AsmResolver.Symbols.Pdb.dll
+  href: symbols/toc.yml
diff --git a/docs/articles/index.md b/docs/articles/index.md
diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml
diff --git a/docs/docfx.json b/docs/docfx.json
@@ -3,34 +3,112 @@
     {
       "src": [
         {
-          "files": [
-                    "**/*.csproj"
-          ],
+          "files": [ "AsmResolver/*.csproj" ],
           "src": "../src"
         }
       ],
-      "dest": "api",
+      "dest": "api/core",
       "includePrivateMembers": false,
       "disableGitFeatures": false,
       "disableDefaultFilter": false,
       "noRestore": false,
       "namespaceLayout": "flattened",
-      "memberLayout": "separatePages",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    },
+    {
+      "src": [
+        {
+          "files": [ "AsmResolver.PE.File/*.csproj" ],
+          "src": "../src"
+        }
+      ],
+      "dest": "api/pe-file",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    },
+    {
+      "src": [
+        {
+          "files": [ "AsmResolver.PE/*.csproj" ],
+          "src": "../src"
+        }
+      ],
+      "dest": "api/pe",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    },
+    {
+      "src": [
+        {
+          "files": [ "AsmResolver.DotNet/*.csproj", "AsmResolver.DotNet.Dynamic/*.csproj" ],
+          "src": "../src"
+        }
+      ],
+      "dest": "api/dotnet",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    },
+    {
+      "src": [
+        {
+          "files": [ "AsmResolver.Symbols.Pdb/*.csproj" ],
+          "src": "../src"
+        }
+      ],
+      "dest": "api/symbols",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    },
+    {
+      "src": [
+        {
+          "files": [ "AsmResolver.PE.Win32Resources/*.csproj" ],
+          "src": "../src"
+        }
+      ],
+      "dest": "api/win32resources",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
       "allowCompilationErrors": false
     }
   ],
   "build": {
     "content": [
       {
         "files": [
-          "api/**.yml",
+          "api/**/*.yml",
           "api/index.md"
         ]
       },
       {
         "files": [
-          "articles/**.md",
-          "articles/**/toc.yml",
+          "guides/**.md",
+          "guides/**/toc.yml",
           "toc.yml",
           "*.md"
         ]
@@ -51,7 +129,14 @@
       "modern",
       "my-template"
     ],
-    "postProcessors": [],
+    "postProcessors": [
+      "ExtractSearchIndex"
+    ],
+    "globalMetadata": {
+      "_enableSearch": "true",
+      "_appTitle": "AsmResolver",
+      "_appName": "AsmResolver"
+    },
     "keepFileLink": false,
     "disableGitFeatures": false
   }

diff --git a/docs/articles/core/segments.md → docs/guides/core/segments.md b/docs/articles/core/segments.md → docs/guides/core/segments.md
@@ -185,8 +185,8 @@ ISegment segment = ...
 // Relocate a segment to an offsets-rva pair:
 segment.UpdateOffsets(new RelocationParameters(offset: 0x200, rva: 0x2000);
 
-Console.WriteLine("Offset: 0x{0:X8}", segment.Offset); // Prints 0x200
-Console.WriteLine("Rva: 0x{0:X8}", segment.Rva);       // Prints 0x2000
+Console.WriteLine($"Offset: 0x{segment.Offset:X8}"); // Prints 0x200
+Console.WriteLine($"Rva: 0x{segment.Rva:X8}");       // Prints 0x2000
 ```
 
 > [!WARNING]
@@ -207,8 +207,8 @@ ISegment segment = ...
 uint physicalSize = segment.GetPhysicalSize();
 uint virtualSize = segment.GetVirtualSize();
 
-Console.WriteLine("Physical (File) Size: 0x{0:X8}", physicalSize);
-Console.WriteLine("Virtual (Runtime) Size: 0x{0:X8}", virtualSize);
+Console.WriteLine($"Physical (File) Size: 0x{physicalSize:X8}");
+Console.WriteLine($"Virtual (Runtime) Size: 0x{virtualSize:X8}");
 ```
 
 > [!WARNING]

diff --git a/...rticles/dotnet/advanced-module-reading.md → .../guides/dotnet/advanced-module-reading.md b/...rticles/dotnet/advanced-module-reading.md → .../guides/dotnet/advanced-module-reading.md
diff --git a/...cles/dotnet/advanced-pe-image-building.md → ...ides/dotnet/advanced-pe-image-building.md b/...cles/dotnet/advanced-pe-image-building.md → ...ides/dotnet/advanced-pe-image-building.md
diff --git a/docs/articles/dotnet/basics.md → docs/guides/dotnet/basics.md b/docs/articles/dotnet/basics.md → docs/guides/dotnet/basics.md
diff --git a/docs/articles/dotnet/bundles.md → docs/guides/dotnet/bundles.md b/docs/articles/dotnet/bundles.md → docs/guides/dotnet/bundles.md
diff --git a/docs/articles/dotnet/cloning.md → docs/guides/dotnet/cloning.md b/docs/articles/dotnet/cloning.md → docs/guides/dotnet/cloning.md
@@ -201,7 +201,7 @@ All references to methods defined in the
 `System.Runtime.CompilerServices` namespace will then be mapped to the
 appropriate method definitions if they exist in the target module.
 
-See [Common Caveats using the Importer](/articles/dotnet/importing.html#common-caveats-using-the-importer)
+See [Common Caveats using the Importer](/guides/dotnet/importing.html#common-caveats-using-the-importer)
 for more information on reference importing and its caveats.
 
 ## Post-processing of cloned members

diff --git a/docs/articles/dotnet/dynamic-methods.md → docs/guides/dotnet/dynamic-methods.md b/docs/articles/dotnet/dynamic-methods.md → docs/guides/dotnet/dynamic-methods.md
@@ -67,6 +67,6 @@ contextModule.GetOrCreateModuleType().Methods.Add(definition);
 contextModule.Write("Program.patched.dll");
 ```
 
-See [Obtaining methods and fields](/articles/dotnet/member-tree.html#obtaining-methods-and-fields)
+See [Obtaining methods and fields](/guides/dotnet/member-tree.html#obtaining-methods-and-fields)
 and [CIL Method Bodies](managed-method-bodies.md) for more
 information on how to use `MethodDefinition` objects.
diff --git a/docs/articles/dotnet/importing.md → docs/guides/dotnet/importing.md b/docs/articles/dotnet/importing.md → docs/guides/dotnet/importing.md
diff --git a/docs/articles/dotnet/index.md → docs/guides/dotnet/index.md b/docs/articles/dotnet/index.md → docs/guides/dotnet/index.md
diff --git a/.../articles/dotnet/managed-method-bodies.md → docs/guides/dotnet/managed-method-bodies.md b/.../articles/dotnet/managed-method-bodies.md → docs/guides/dotnet/managed-method-bodies.md
diff --git a/docs/articles/dotnet/managed-resources.md → docs/guides/dotnet/managed-resources.md b/docs/articles/dotnet/managed-resources.md → docs/guides/dotnet/managed-resources.md
@@ -191,9 +191,9 @@ includes the name, the type of the resource and the deserialized data:
 ``` csharp
 foreach (var entry in set)
 {
-    Console.WriteLine("Name: " + entry.Name);
-    Console.WriteLine("Type: " + entry.Type.FullName);
-    Console.WriteLine("Data: " + entry.Data);
+    Console.WriteLine($"Name: {entry.Name}");
+    Console.WriteLine($"Type: {entry.Type.FullName}");
+    Console.WriteLine($"Data: {entry.Data}");
 }
 ```
 

diff --git a/docs/articles/dotnet/member-tree.md → docs/guides/dotnet/member-tree.md b/docs/articles/dotnet/member-tree.md → docs/guides/dotnet/member-tree.md
@@ -47,7 +47,7 @@ private static void DumpTypes(IEnumerable<TypeDefinition> types, int indentation
     foreach (var type in types)
     {
         // Print the name of the current type.
-        Console.WriteLine("{0}- {1} : {2:X8}", indentation, type.Name, type.MetadataToken.ToInt32());
+        Console.WriteLine($"{indentation}- {type.Name} : {type.MetadataToken}");
 
         // Dump any nested types.
         DumpTypes(type.NestedTypes, indentationLevel + 1);
@@ -62,26 +62,26 @@ that the type defines:
 
 ``` csharp
 foreach (var method in type.Methods)
-    Console.WriteLine("{0} : {1:X8}", method.Name, method.MetadataToken.ToInt32());
+    Console.WriteLine($"{method.Name} : {method.MetadataToken}");
 ```
 
 ``` csharp
 foreach (var field in type.Fields)
-    Console.WriteLine("{0} : {1:X8}", field.Name, field.MetadataToken.ToInt32());
+    Console.WriteLine($"{field.Name} : {field.MetadataToken}");
 ```
 
 Methods and fields have a `Signature` property, that contain the return
 and parameter types, or the field type respectively.
 
 ``` csharp
 MethodDefinition method = ...
-Console.WriteLine("Return type: " + method.Signature.ReturnType);
-Console.WriteLine("Parameter types: " + string.Join(", ", method.Signature.ParameterTypes));
+Console.WriteLine($"Return type:     {method.Signature.ReturnType}");
+Console.WriteLine($"Parameter types: {string.Join(", ", method.Signature.ParameterTypes)}");
 ```
 
 ``` csharp
 FieldDefinition field = ...
-Console.WriteLine("Field type: " + field.Signature.FieldType);
+Console.WriteLine($"Field type: {field.Signature.FieldType}");
 ```
 
 However, for reading parameters from a method definition, it is
@@ -103,12 +103,12 @@ fields; `TypeDefinition` exposes them in a list as well:
 
 ``` csharp
 foreach (var @event in type.Events)
-    Console.WriteLine("{0} : {1:X8}", @event.Name, @event.MetadataToken.ToInt32());
+    Console.WriteLine($"{@event.Name} : {@event.MetadataToken}");
 ```
 
 ``` csharp
 foreach (var property in type.Properties)
-    Console.WriteLine("{0} : {1:X8}", property.Name, property.MetadataToken.ToInt32());
+    Console.WriteLine($"{property.Name} : {property.MetadataToken}");
 ```
 
 Properties and events have methods associated to them. These are
@@ -117,7 +117,6 @@ accessible through the `Semantics` property:
 ``` csharp
 foreach (MethodSemantics semantic in property.Semantics)
 {
-    Console.WriteLine("{0} {1} : {2:X8}", semantic.Attributes, semantic.Method.Name,
-        semantic.MetadataToken.ToInt32());
+    Console.WriteLine($"{semantic.Attributes} {semantic.Method.Name} : {semantic.MetadataToken}");
 }
 ```
diff --git a/docs/articles/dotnet/token-allocation.md → docs/guides/dotnet/token-allocation.md b/docs/articles/dotnet/token-allocation.md → docs/guides/dotnet/token-allocation.md
diff --git a/docs/articles/dotnet/type-memory-layout.md → docs/guides/dotnet/type-memory-layout.md b/docs/articles/dotnet/type-memory-layout.md → docs/guides/dotnet/type-memory-layout.md
diff --git a/docs/articles/dotnet/type-signatures.md → docs/guides/dotnet/type-signatures.md b/docs/articles/dotnet/type-signatures.md → docs/guides/dotnet/type-signatures.md
diff --git a/...rticles/dotnet/unmanaged-method-bodies.md → .../guides/dotnet/unmanaged-method-bodies.md b/...rticles/dotnet/unmanaged-method-bodies.md → .../guides/dotnet/unmanaged-method-bodies.md
diff --git a/docs/articles/faq.md → docs/guides/faq.md b/docs/articles/faq.md → docs/guides/faq.md
@@ -25,9 +25,9 @@ writing).
 
 AsmResolver often can ignore and recover from kinds of errors, but this
 is not enabled by default. To enable these, please refer to
-[Advanced PE Image Reading](/articles/peimage/advanced-pe-reading.html#custom-error-handling) (PE)
-or [Advanced Module Reading](/articles/dotnet/advanced-module-reading.html#pe-image-reading-parameters) (.NET),
-and [Image Builder Diagnostics](/articles/dotnet/advanced-pe-image-building.html#image-builder-diagnostics) (.NET).
+[Advanced PE Image Reading](/guides/peimage/advanced-pe-reading.html#custom-error-handling) (PE)
+or [Advanced Module Reading](/guides/dotnet/advanced-module-reading.html#pe-image-reading-parameters) (.NET),
+and [Image Builder Diagnostics](/guides/dotnet/advanced-pe-image-building.html#image-builder-diagnostics) (.NET).
 Be careful with ignoring errors though. Especially for disabling writer
 verification can cause the output to not work anymore unless you know
 what you are doing.

diff --git a/docs/articles/overview.md → docs/guides/overview.md b/docs/articles/overview.md → docs/guides/overview.md
diff --git a/docs/articles/pdb/basics.md → docs/guides/pdb/basics.md b/docs/articles/pdb/basics.md → docs/guides/pdb/basics.md
diff --git a/docs/articles/pdb/index.md → docs/guides/pdb/index.md b/docs/articles/pdb/index.md → docs/guides/pdb/index.md