Skip to content

Commit d238818

Browse files
committed
Refactor documentation descriptions in JSON schemas to improve readability
- Updated descriptions in various JSON schema files to include line breaks for better formatting. - Enhanced clarity in descriptions for processors and tools related to TFS migration. - Adjusted code documentation in the ConsoleDataGenerator to utilize a new Markdown conversion method for XML documentation.
1 parent 8cbabe6 commit d238818

File tree

32 files changed

+168
-90
lines changed

32 files changed

+168
-90
lines changed

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

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ configurationSamples:
2626
"TargetName": null
2727
}
2828
sampleFor: MigrationTools.Processors.TfsExportUsersForMappingProcessorOptions
29-
description: ExportUsersForMappingContext is a tool used to create a starter mapping file for users between the source and target systems. Use `ExportUsersForMappingConfig` to configure.
29+
description: >-
30+
ExportUsersForMappingContext is a tool used to create a starter mapping file for users between the source and target systems.
31+
Use `ExportUsersForMappingConfig` to configure.
3032
className: TfsExportUsersForMappingProcessor
3133
typeName: Processors
3234
options:
@@ -44,7 +46,10 @@ options:
4446
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
4547
- parameterName: ExportAllUsers
4648
type: Boolean
47-
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`.
49+
description: >-
50+
Set to `true`, if you want to export all users in source and target server.
51+
The lists of user can be useful, if you need tu manually edit mapping file.
52+
Users will be exported to file set in `UserExportFile`.
4853
defaultValue: missing XML code comments
4954
isRequired: false
5055
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -74,7 +79,9 @@ options:
7479
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
7580
- parameterName: UserExportFile
7681
type: String
77-
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`.
82+
description: >-
83+
Path to export file where all source and target servers' users will be exported.
84+
Users are exported only if `ExportAllUsers` is set to `true`.
7885
defaultValue: missing XML code comments
7986
isRequired: false
8087
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,10 @@ options:
9494
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
9595
- parameterName: UseUserMapping
9696
type: Boolean
97-
description: Use user mapping file from TfsTeamSettingsTool when matching users when migrating capacities. By default, users in source are matched in target users by current display name. When this is set to `true`, users are matched also by mapped name from user mapping file.
97+
description: >-
98+
Use user mapping file from TfsTeamSettingsTool when matching users when migrating capacities.
99+
By default, users in source are matched in target users by current display name. When this is set to `true`,
100+
users are matched also by mapped name from user mapping file.
98101
defaultValue: missing XML code comments
99102
isRequired: false
100103
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,9 @@ options:
9595
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
9696
- parameterName: TestPlanIds
9797
type: Int32[]
98-
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.'
98+
description: >-
99+
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]
100+
Works optimally when "TestPlanQuery" is set to null.
99101
defaultValue: missing XML code comments
100102
isRequired: false
101103
dotNetType: System.Int32[], System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@ options:
4646
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
4747
- parameterName: FilterWorkItemsThatAlreadyExistInTarget
4848
type: Boolean
49-
description: This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run. While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.
49+
description: >-
50+
This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run.
51+
While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.
5052
defaultValue: true
5153
isRequired: false
5254
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -88,7 +90,9 @@ options:
8890
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
8991
- parameterName: WorkItemCreateRetryLimit
9092
type: Int32
91-
description: '**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count. This allows for periodic network glitches not to end the process.'
93+
description: >-
94+
**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count.
95+
This allows for periodic network glitches not to end the process.
9296
defaultValue: 5
9397
isRequired: false
9498
dotNetType: System.Int32, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,9 @@ configurationSamples:
2727
"TargetName": null
2828
}
2929
sampleFor: MigrationTools.Processors.TfsWorkItemDeleteProcessorOptions
30-
description: The `WorkItemDelete` processor allows you to delete any amount of work items that meet the query. **DANGER:** This is not a recoverable action and should be use with extream caution.
30+
description: >-
31+
The `WorkItemDelete` processor allows you to delete any amount of work items that meet the query.
32+
**DANGER:** This is not a recoverable action and should be use with extream caution.
3133
className: TfsWorkItemDeleteProcessor
3234
typeName: Processors
3335
options:

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

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,9 @@ configurationSamples:
7070
"TargetName": "Target"
7171
}
7272
sampleFor: MigrationTools.Processors.TfsWorkItemMigrationProcessorOptions
73-
description: WorkItemMigrationConfig is the main processor used to Migrate Work Items, Links, and Attachments. Use `WorkItemMigrationConfig` to configure.
73+
description: >-
74+
WorkItemMigrationConfig is the main processor used to Migrate Work Items, Links, and Attachments.
75+
Use `WorkItemMigrationConfig` to configure.
7476
className: TfsWorkItemMigrationProcessor
7577
typeName: Processors
7678
options:
@@ -94,13 +96,18 @@ options:
9496
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
9597
- parameterName: FilterWorkItemsThatAlreadyExistInTarget
9698
type: Boolean
97-
description: This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run. While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.
99+
description: >-
100+
This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run.
101+
While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.
98102
defaultValue: true
99103
isRequired: false
100104
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
101105
- parameterName: FixHtmlAttachmentLinks
102106
type: Boolean
103-
description: "**beta** If enabled this will fix any image attachments URL's, work item mention URL's or user mentions in the HTML fields as well as discussion comments. You must specify a PersonalAccessToken in the Source project for Azure DevOps; TFS should use integrated authentication."
107+
description: >-
108+
**beta** If enabled this will fix any image attachments URL's, work item mention URL's or user mentions in the HTML
109+
fields as well as discussion comments. You must specify a PersonalAccessToken in the Source project for Azure DevOps;
110+
TFS should use integrated authentication.
104111
defaultValue: true
105112
isRequired: false
106113
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -112,7 +119,9 @@ options:
112119
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
113120
- parameterName: MaxGracefulFailures
114121
type: Int32
115-
description: The maximum number of failures to tolerate before the migration fails. When set above zero, a work item migration error is logged but the migration will continue until the number of failed items reaches the configured value, after which the migration fails.
122+
description: >-
123+
The maximum number of failures to tolerate before the migration fails. When set above zero, a work item migration error is logged but the migration will
124+
continue until the number of failed items reaches the configured value, after which the migration fails.
116125
defaultValue: 0
117126
isRequired: false
118127
dotNetType: System.Int32, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -154,13 +163,19 @@ options:
154163
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
155164
- parameterName: UpdateCreatedBy
156165
type: Boolean
157-
description: "If this is enabled the creation process on the target project will create the items with the original creation date. (Important: The item history is always pointed to the date of the migration, it's change only the data column CreateDate, not the internal create date)"
166+
description: >-
167+
If this is enabled the creation process on the target project will create the items with the original creation date.
168+
(Important: The item history is always pointed to the date of the migration, it's change only the data column CreateDate,
169+
not the internal create date)
158170
defaultValue: true
159171
isRequired: false
160172
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
161173
- parameterName: UpdateCreatedDate
162174
type: Boolean
163-
description: "If this is enabled the creation process on the target project will create the items with the original creation date. (Important: The item history is always pointed to the date of the migration, it's change only the data column CreateDate, not the internal create date)"
175+
description: >-
176+
If this is enabled the creation process on the target project will create the items with the original creation date.
177+
(Important: The item history is always pointed to the date of the migration, it's change only the data column CreateDate,
178+
not the internal create date)
164179
defaultValue: true
165180
isRequired: false
166181
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -172,7 +187,9 @@ options:
172187
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
173188
- parameterName: WorkItemCreateRetryLimit
174189
type: Int32
175-
description: '**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count. This allows for periodic network glitches not to end the process.'
190+
description: >-
191+
**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count.
192+
This allows for periodic network glitches not to end the process.
176193
defaultValue: 5
177194
isRequired: false
178195
dotNetType: System.Int32, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,9 @@ options:
4545
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
4646
- parameterName: FilterWorkItemsThatAlreadyExistInTarget
4747
type: Boolean
48-
description: This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run. While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.
48+
description: >-
49+
This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run.
50+
While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.
4951
defaultValue: true
5052
isRequired: false
5153
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
@@ -81,7 +83,9 @@ options:
8183
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
8284
- parameterName: WorkItemCreateRetryLimit
8385
type: Int32
84-
description: '**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count. This allows for periodic network glitches not to end the process.'
86+
description: >-
87+
**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count.
88+
This allows for periodic network glitches not to end the process.
8589
defaultValue: 5
8690
isRequired: false
8791
dotNetType: System.Int32, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,10 @@ configurationSamples:
2323
"TargetName": null
2424
}
2525
sampleFor: MigrationTools.Processors.TfsWorkItemTypeValidatorProcessorOptions
26-
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.
26+
description: >-
27+
Work item type validation processor. Basically it just runs the `TfsWorkItemTypeValidatorTool`
28+
to validate work item types. The validation is run always, even if the tool iself is disabled.
29+
Neither this processor, nor the tool do not perform any changes to the source or target system.
2730
className: TfsWorkItemTypeValidatorProcessor
2831
typeName: Processors
2932
options:
@@ -53,7 +56,11 @@ options:
5356
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
5457
- parameterName: StopIfValidationFails
5558
type: Boolean
56-
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`.
59+
description: >-
60+
If set to `true`, migration process will stop if there are some validation errors.
61+
If set to `false`, migration process will continue, for example to support some other validation
62+
processors.
63+
Default value is `true`.
5764
defaultValue: missing XML code comments
5865
isRequired: false
5966
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,9 @@ options:
6666
dotNetType: System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e
6767
- parameterName: MaxAttachmentSize
6868
type: Int32
69-
description: '`AttachmentMigration` is set to true then you need to specify a max file size for upload in bites. For Azure DevOps Services the default is 480,000,000 bites (60mb), for TFS its 32,000,000 bites (4mb).'
69+
description: >-
70+
`AttachmentMigration` is set to true then you need to specify a max file size for upload in bites.
71+
For Azure DevOps Services the default is 480,000,000 bites (60mb), for TFS its 32,000,000 bites (4mb).
7072
defaultValue: 480000000
7173
isRequired: false
7274
dotNetType: System.Int32, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

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

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,12 @@ options:
115115
dotNetType: MigrationTools.Tools.NodeOptions, MigrationTools.Clients.TfsObjectModel, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
116116
- parameterName: MigrateRootNodes
117117
type: Boolean
118-
description: By default, only child nodes in node structures are migrated. Turning this on migrates even the root node (default area/iteration). This is useful, when you do not have any child areas ion source, but want to migrate default area in source to some sub-area in target project. You have to set proper mapping for this to work. If after mapping the target node is still just root node (so it is not migrated under some child node), nothing happens – so migrating root nodes works only if the are remapped to some child node in target project.
118+
description: >-
119+
By default, only child nodes in node structures are migrated. Turning this on migrates even the root node
120+
(default area/iteration). This is useful, when you do not have any child areas ion source, but want to migrate
121+
default area in source to some sub-area in target project. You have to set proper mapping for this to work.
122+
If after mapping the target node is still just root node (so it is not migrated under some child node),
123+
nothing happens – so migrating root nodes works only if the are remapped to some child node in target project.
119124
defaultValue: missing XML code comments
120125
isRequired: false
121126
dotNetType: System.Boolean, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e

0 commit comments

Comments
 (0)