Add Documentation Generator launch configuration and improve XML documentation handling

- Added a new launch configuration for the Documentation Generator in launch.json.
- Updated descriptions in YAML files for ExportAllUsers and UserExportFile parameters to clarify usage.
- Fixed formatting issues in various YAML files, replacing "& Plans" with "& Plans".
- Enhanced the GetXDocument methods in CodeDocumentation.cs to preserve XML tags when converting to Markdown.
- Introduced XmlDocToMarkdownConverter.cs to handle XML documentation to Markdown conversion, including support for various XML tags.
- Updated JSON schema files to reflect changes in descriptions and ensure consistency across documentation.

Author: MrHinsh

.vscode/launch.json

@@ -39,6 +39,21 @@
             "type": "coreclr",
             "request": "attach",
             "processId": "${command:azureFunctions.pickProcess}"
+        },
+        {
+            "name": "Documentation Generator",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build only",
+            "program": "${workspaceFolder}/src/MigrationTools.ConsoleDataGenerator/bin/Debug/net8.0/MigrationTools.ConsoleDataGenerator.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/src/MigrationTools.ConsoleDataGenerator/bin/Debug/net8.0",
+            "console": "internalConsole",
+            "stopAtEntry": false,
+            "justMyCode": true,
+            "env": {
+                "DOTNET_ENVIRONMENT": "Development"
+            }
         }
     ]
 }

docs/data/classes/reference.processors.tfsexportusersformappingprocessor.yaml

@@ -44,7 +44,7 @@ options:
   dotNetType: System.Collections.Generic.List`1[[MigrationTools.Enrichers.IProcessorEnricherOptions, MigrationTools, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null]], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: ExportAllUsers
   type: Boolean
-  description: Set to , if you want to export all users in source and target server. The lists of user can be useful, if you need tu manually edit mapping file. Users will be exported to file set in .
+  description: Set to `true`, if you want to export all users in source and target server. The lists of user can be useful, if you need tu manually edit mapping file. Users will be exported to file set in `UserExportFile`.
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -74,7 +74,7 @@ options:
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: UserExportFile
   type: String
-  description: Path to export file where all source and target servers' users will be exported. Users are exported only if  is set to .
+  description: Path to export file where all source and target servers' users will be exported. Users are exported only if `ExportAllUsers` is set to `true`.
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

docs/data/classes/reference.processors.tfstestconfigurationsmigrationprocessor.yaml

@@ -57,6 +57,6 @@ options:
   isRequired: true
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 status: Beta
-processingTarget: Suites & Plans
+processingTarget: Suites & Plans
 classFile: src/MigrationTools.Clients.TfsObjectModel/Processors/TfsTestConfigurationsMigrationProcessor.cs
 optionsClassFile: src/MigrationTools.Clients.TfsObjectModel/Processors/TfsTestConfigurationsMigrationProcessorOptions.cs

docs/data/classes/reference.processors.tfstestplansandsuitesmigrationprocessor.yaml

@@ -95,7 +95,7 @@ options:
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: TestPlanIds
   type: Int32[]
-  description: 'This flag filters all test plans and retains only the specified ones for migration. Pass the test plan IDs as an array. Example: "TestPlanIds": [123, 456, 789]   Works optimally when "TestPlanQuery" is set to null.'
+  description: 'This flag filters all test plans and retains only the specified ones for migration. Pass the test plan IDs as an array. Example: "TestPlanIds": [123, 456, 789] Works optimally when "TestPlanQuery" is set to null.'
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.Int32[], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -106,6 +106,6 @@ options:
   isRequired: false
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 status: Beta
-processingTarget: Suites & Plans
+processingTarget: Suites & Plans
 classFile: src/MigrationTools.Clients.TfsObjectModel/Processors/TfsTestPlansAndSuitesMigrationProcessor.cs
 optionsClassFile: src/MigrationTools.Clients.TfsObjectModel/Processors/TfsTestPlansAndSuitesMigrationProcessorOptions.cs

docs/data/classes/reference.processors.tfstestvariablesmigrationprocessor.yaml

@@ -58,6 +58,6 @@ options:
   isRequired: true
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 status: Beta
-processingTarget: Suites & Plans
+processingTarget: Suites & Plans
 classFile: src/MigrationTools.Clients.TfsObjectModel/Processors/TfsTestVariablesMigrationProcessor.cs
 optionsClassFile: src/MigrationTools.Clients.TfsObjectModel/Processors/TfsTestVariablesMigrationProcessorOptions.cs

docs/data/classes/reference.processors.tfsworkitembulkeditprocessor.yaml

@@ -83,7 +83,7 @@ options:
 - parameterName: WIQLQuery
   type: String
   description: A work item query based on WIQL to select only important work items. To migrate all leave this empty. See [WIQL Query Bits](#wiql-query-bits)
-  defaultValue: AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request')
+  defaultValue: AND [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request')
   isRequired: true
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: WorkItemCreateRetryLimit

docs/data/classes/reference.processors.tfsworkitemoverwriteprocessor.yaml

@@ -76,7 +76,7 @@ options:
 - parameterName: WIQLQuery
   type: String
   description: A work item query based on WIQL to select only important work items. To migrate all leave this empty. See [WIQL Query Bits](#wiql-query-bits)
-  defaultValue: AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request')
+  defaultValue: AND [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request')
   isRequired: true
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: WorkItemCreateRetryLimit

docs/data/classes/reference.processors.tfsworkitemtypevalidatorprocessor.yaml

@@ -23,7 +23,7 @@ configurationSamples:
       "TargetName": null
     }
   sampleFor: MigrationTools.Processors.TfsWorkItemTypeValidatorProcessorOptions
-description: Work item type validation processor. Basically it just runs the  to validate work item types. The validation is run always, even if the tool iself is disabled. Neither this processor, nor the tool do not perform any changes to the source or target system.
+description: Work item type validation processor. Basically it just runs the `TfsWorkItemTypeValidatorTool` to validate work item types. The validation is run always, even if the tool iself is disabled. Neither this processor, nor the tool do not perform any changes to the source or target system.
 className: TfsWorkItemTypeValidatorProcessor
 typeName: Processors
 options:
@@ -53,7 +53,7 @@ options:
   dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: StopIfValidationFails
   type: Boolean
-  description: If set to , migration process will stop if there are some validation errors. If set to , migration process will continue, for example to support some other validation processors. Default value is .
+  description: If set to `true`, migration process will stop if there are some validation errors. If set to `false`, migration process will continue, for example to support some other validation processors. Default value is `true`.
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

docs/data/classes/reference.tools.tfsvalidaterequiredfieldtool.yaml

@@ -9,35 +9,16 @@ configurationSamples:
 - name: sample
   order: 1
   description: 
-  code: >-
-    {
-      "MigrationTools": {
-        "Version": "16.0",
-        "CommonTools": {
-          "TfsValidateRequiredFieldTool": {
-            "Enabled": "True",
-            "Exclusions": [
-              "Work Request",
-              "Opertunity",
-              "Assumption"
-            ]
-          }
-        }
-      }
-    }
+  code: There is no sample, but you can check the classic below for a general feel.
   sampleFor: MigrationTools.Tools.TfsValidateRequiredFieldToolOptions
 - name: classic
   order: 3
   description: 
   code: >-
     {
       "$type": "TfsValidateRequiredFieldToolOptions",
-      "Enabled": true,
-      "Exclusions": [
-        "Work Request",
-        "Opertunity",
-        "Assumption"
-      ]
+      "Enabled": false,
+      "Exclusions": []
     }
   sampleFor: MigrationTools.Tools.TfsValidateRequiredFieldToolOptions
 description: Tool for validating that required fields exist in target work item types before migration, preventing migration failures due to missing required fields.

docs/data/classes/reference.tools.tfsworkitemtypevalidatortool.yaml

@@ -26,10 +26,10 @@ configurationSamples:
         "CommonTools": {
           "TfsWorkItemTypeValidatorTool": {
             "Enabled": "True",
-            "FieldMappings": {
-              "User Story": {
-                "Microsoft.VSTS.Common.Prirucka": "Custom.Prirucka"
-              }
+            "FixedTargetFields": {
+              "User Story": [
+                "Custom.Prirucka"
+              ]
             },
             "IncludeWorkItemtypes": [
               "Bug",
@@ -39,7 +39,12 @@ configurationSamples:
               "Feature",
               "Epic",
               "Risk"
-            ]
+            ],
+            "SourceFieldMappings": {
+              "User Story": {
+                "Microsoft.VSTS.Common.Prirucka": "Custom.Prirucka"
+              }
+            }
           }
         }
       }
@@ -61,8 +66,16 @@ configurationSamples:
         "Epic",
         "Risk"
       ],
-      "SourceFieldMappings": {},
-      "FixedTargetFields": {}
+      "SourceFieldMappings": {
+        "User Story": {
+          "Microsoft.VSTS.Common.Prirucka": "Custom.Prirucka"
+        }
+      },
+      "FixedTargetFields": {
+        "User Story": [
+          "Custom.Prirucka"
+        ]
+      }
     }
   sampleFor: MigrationTools.Tools.TfsWorkItemTypeValidatorToolOptions
 description: This tool checks if the work item types in the source system have corresponding types in the target system, and validates their fields and mappings.
@@ -77,19 +90,19 @@ options:
   dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: FixedTargetFields
   type: Dictionary
-  description: List of target fields, that are considered as fixed. It means, even if the field is different against source field, no warning will be triggered, jus information about the differences. Use this list, whan you know about the differences between fields, but resolved it for example by using .  Key is target work item type name. As this name, you can use * to define fixed fields which will be applied to all work item types.
+  description: List of target fields that are considered as `fixed`. A field marked as fixed will not stop the migration if differences are found. Instead of a warning, only an informational message will be logged. Use this list when you already know about the differences and have resolved them, for example by using `FieldMappingTool`. The key is the target work item type name. You can also use `*` to define fixed fields that apply to all work item types.
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e],[System.Collections.Generic.List`1[[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: IncludeWorkItemtypes
   type: List
   description: List of work item types which will be validated. If this list is empty, all work item types will be validated.
-  defaultValue: missing XML code comments
+  defaultValue: All work item types are included.
   isRequired: false
   dotNetType: System.Collections.Generic.List`1[[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
 - parameterName: SourceFieldMappings
   type: Dictionary
-  description: Field reference name mappings. Key is work item type name, value is dictionary of mapping source filed name to target field name. Target field name can be empty string to indicate that this field will not be validated in target. As work item type name, you can use * to define mappings which will be applied to all work item types.
+  description: Field reference name mappings. Key is work item type name, value is dictionary of mapping source filed name to target field name. Target field name can be empty string to indicate that this field will not be validated in target. As work item type name, you can use `*` to define mappings which will be applied to all work item types.
   defaultValue: missing XML code comments
   isRequired: false
   dotNetType: System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e],[System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e],[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e