Merge pull request stride3d#169 from VaclavElias/master

Diagnostics docs content improvements

Author: VaclavElias

Diff for: BuildDocs.ps1

@@ -83,22 +83,26 @@ function Ask-IncludeAPI {
     Write-Host ""
     Write-Host -ForegroundColor Cyan "Do you want to include API?"
     Write-Host ""
-    Write-Host -ForegroundColor Yellow "  [Y] Yes"
+    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
     Write-Host -ForegroundColor Yellow "  [N] No"
     Write-Host ""
 
-    return (Read-Host -Prompt "Your choice (Y/N)").ToLower() -eq "y"
+    $input = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"
+
+    return ($input -eq "Y" -or $input -eq "y" -or $input -eq "")
 }
 
 function Ask-UseExistingAPI {
     Write-Host ""
     Write-Host -ForegroundColor Cyan "Do you want to use already generated API metadata?"
     Write-Host ""
-    Write-Host -ForegroundColor Yellow "  [Y] Yes"
+    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
     Write-Host -ForegroundColor Yellow "  [N] No"
     Write-Host ""
 
-    return (Read-Host -Prompt "Your choice (Y/N)").ToLower() -eq "y"
+    $input = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"
+
+    return ($input -eq "Y" -or $input -eq "y" -or $input -eq "")
 }
 
 function Copy-ExtraItems {
@@ -446,8 +450,15 @@ else {
     {
         $API = Ask-IncludeAPI
 
-        if ($API) {
-            $ReuseAPI = Ask-UseExistingAPI
+        if ($API)
+        {
+            # Check for .yml files
+            $ymlFiles = Get-ChildItem -Path "en/api/" -Filter "*.yml"
+
+            if ($ymlFiles.Count -gt 0)
+            {
+                $ReuseAPI = Ask-UseExistingAPI
+            }
         }
 
     } elseif ($isCanceled) {

Diff for: en/diagnostics/STRDIAG000.md

@@ -6,7 +6,7 @@
 ## Explanation
 
 Adding @Stride.Core.DataMemberAttribute and @Stride.Core.DataMemberIgnoreAttribute to the same member is not supported. This would be a contradiction.
-It would mean the Serializer should serialize the member and ignore it at the same time. The @Stride.Updater.DataMemberUpdatableAttribute  makes the combination valid again as it negates the @Stride.Core.DataMemberIgnoreAttribute for the binary Serializer.
+It would mean the serializer should serialize the member and ignore it at the same time. The @Stride.Updater.DataMemberUpdatableAttribute  makes the combination valid again as it negates the @Stride.Core.DataMemberIgnoreAttribute for the binary serializer.
 
 ## Example: Invalid cases
 
@@ -49,8 +49,8 @@ public class STRDIAG000
 ## Solution
 
 > To resolve the warning, pick either the @Stride.Core.DataMemberAttribute or the @Stride.Core.DataMemberIgnoreAttribute.
-If the `YamlSerializer` and the Editor should ignore the member but the binary Serializer not, then add the @Stride.Core.DataMemberIgnoreAttribute.
+If the `YamlSerializer` and the Editor should ignore the member but the binary serializer not, then add the @Stride.Core.DataMemberIgnoreAttribute.
 
 ## References
 
-- [Serialisation](../manual/scripts/serialization.md)
+- [Serialisation](../manual/scripts/serialization.md)

Diff for: en/diagnostics/STRDIAG001.md

@@ -4,7 +4,7 @@
 
 ## Explanation
 
-The @Stride.Core.DataContractAttribute can only be applied to public/internal type. Any lower Access  will cause STRDIAG001 on the target type.
+The @Stride.Core.DataContractAttribute can only be applied to `public`/`internal` type. Any lower access will cause STRDIAG001 on the target type.
 
 ## Example: private inner class
 
@@ -33,7 +33,7 @@ file class STRDIAG001
 
 ## Solution
 
-To resolve the warning, increase the accessibility of the type to pulic/internal or remove the @Stride.CoreDataContractAttribute .
+To resolve the warning, increase the accessibility of the type to `public`/`internal` or remove the @Stride.Core.DataContractAttribute.
 
 ## References
 

Diff for: en/diagnostics/STRDIAG002.md

@@ -5,9 +5,8 @@
 
 ## Explanation
 
-The Content Mode mutates the object which is currently in the member.
-As this is not possible with the current Serializers, only mutable Types are supported for Content Mode.
-Immutable types in this context are none reference types and string.
+The [DataMemberMode.Content](xref:Stride.Core.DataMemberMode) mutates the object which is currently in the member.
+As this is not possible with the current serializers, only mutable types are supported for `DataMemberMode.Content`. Immutable types in this context are none reference types and string.
 
 ## Example
 
@@ -19,7 +18,7 @@ using Stride.Core;
 public class STRDIAG002
 {
     [DataMember(DataMemberMode.Content)]
-    public int Value { get; set;}
+    public int Value { get; set; }
 
     [DataMember(DataMemberMode.Content)]
     public string Value;
@@ -28,4 +27,4 @@ public class STRDIAG002
 
 ## Solution
 
-To resolve the warning, pick either a reference type for the member or use `DataMemberMode.Assign` for Immutable types.
+To resolve the warning, pick either a reference type for the member or use `DataMemberMode.Assign` for Immutable types.

Diff for: en/diagnostics/STRDIAG003.md

@@ -1,12 +1,11 @@
 # Diagnostics Warning STRDIAG003
 
-> The member '{0}' with `[DataMember]` is not accesssible to the serializer. Only public/internal/internal > protected visibility is supported, when the `[DataMember]` attribute is applied.
+> The member '{0}' with `[DataMember]` is not accessible to the serializer. Only public/internal/internal > protected visibility is supported, when the `[DataMember]` attribute is applied.
 
 ## Explanation
 
-The Serialization concept in Stride expects public/internal/internal protected visibility of properties.
-Other Accessibility won't be considered for Serialization.
-To count internal/internal protected as visible to the Editor the @Stride.Core.DataMemberAttribute has to be applied, else it's considered as not visible.
+The serialization concept in Stride expects `public`/`internal`/`internal protected` visibility of properties. Other accessibility won't be considered for serialization.
+To count `internal`/`internal protected` as visible to the Editor the @Stride.Core.DataMemberAttribute has to be applied, else it's considered as not visible.
 
 ## Example
 
@@ -18,7 +17,7 @@ using Stride.Core;
 public class STRDIAG003
 {
     [DataMember]
-    private int Value { get; set;}
+    private int Value { get; set; }
 
     [DataMember]
     protected string Value;
@@ -30,4 +29,4 @@ public class STRDIAG003
 
 ## Solution
 
-To resolve the warning, increase the Accessibility to public/internal/internal protected of the member or remove the @Stride.Core.DataMemberAttribute Attribute.
+To resolve the warning, increase the Accessibility to `public`/`internal`/`internal protected` of the member or remove the @Stride.Core.DataMemberAttribute Attribute.

Diff for: en/diagnostics/STRDIAG004.md

@@ -5,10 +5,10 @@
 
 ## Explanation
 
-All Serializers need a getter on a property to be able to get the content of the property.
-This is required for all Serializers in Stride.
-Non existent getters will result in error message 1.
-Non visible getters will result in error message 2.
+All serializers need a getter on a property to be able to get the content of the property.
+This is required for all serializers in Stride.
+- Non existent getters will result in error message 1.
+- Non visible getters will result in error message 2.
 
 ## Example
 
@@ -34,8 +34,8 @@ public class STRDIAG004
 ```
 
 > [!WARNING]
-> There is an edge case with internal/internal protected, it will count as non visible when the @Stride.Core.DataMemberAttribute isn't applied.
-> But when the Attribute is applied then the getter counts as visible and therfore is correct.
+> There is an edge case with `internal`/`internal protected`, it will count as non visible when the @Stride.Core.DataMemberAttribute isn't applied.
+> But when the attribute is applied then the getter counts as visible and therefore is correct.
 
 ```csharp
 // STRDIAG000.cs
@@ -44,10 +44,10 @@ using Stride.Core;
 public class STRDIAG004
 {
     // will throw STRDIAG004
-    public int Value { internal get; set;}
+    public int Value { internal get; set; }
 
     // will throw STRDIAG004
-    public int Value { internal protected get; set;}
+    public int Value { internal protected get; set; }
 
     // won't throw STRDIAG004
     [DataMember]
@@ -61,6 +61,6 @@ public class STRDIAG004
 
 ## Solution
 
-To resolve the warning 1, add a getter to the property with a public/internal/internal protected Accessibility or remove the @Stride.Core.DataMemberAttribute .
+To resolve the warning 1, add a getter to the property with a `public`/`internal`/`internal protected` accessibility or remove the @Stride.Core.DataMemberAttribute .
 
-To resolve the warning 2, increase the Accessibility of the property getter to public/internal/internal protected Accessibility or remove the @Stride.Core.DataMemberAttribute .
+To resolve the warning 2, increase the accessibility of the property getter to `public`/`internal`/`internal protected` accessibility or remove the @Stride.Core.DataMemberAttribute .

Diff for: en/diagnostics/STRDIAG005.md

@@ -4,7 +4,7 @@
 
 ## Explanation
 
-Having no set possibility automatically lets the serializers automatically use the `DataMemberMode.Content.`
+Having no set possibility automatically lets the serializers automatically use the [DataMemberMode.Content](xref:Stride.Core.DataMemberMode).
 For immutable types the `DataMemberMode.Content` is never valid.
 Immutable types in this context are none reference types and string.
 
@@ -26,5 +26,6 @@ public class STRDIAG005
 
 ## Solution
 
-To resolve the warning for fields, remove the \[DataMember] Attribute or remove the readonly modifier.
-To resolve the warning for properties, alter the type of the property to a supported type or remove the \[DataMember] Attribute.
+To resolve the warning for fields, remove the `[DataMember]` attribute or remove the `readonly` modifier.
+
+To resolve the warning for properties, alter the type of the property to a supported type or remove the `[DataMember]` attribute.

Diff for: en/diagnostics/STRDIAG006.md

@@ -1,11 +1,10 @@
 # Diagnostics Warning STRDIAG006
 
-> Invalid DataMembermode for the specified `[DataMember]` member '{0}'. A public/internal/internal protected setter is required for 'DataMemberMode.Assign'.
+> Invalid DataMemberMode for the specified `[DataMember]` member '{0}'. A public/internal/internal protected setter is required for 'DataMemberMode.Assign'.
 
 ## Explanation
 
-The @Stride.Core.DataMemberMode.Assign let's the Serializers create new objects and sets them into the target property.
-The Property needs an accessible/visible setter.
+The @Stride.Core.DataMemberMode.Assign let's the serializers create new objects and sets them into the target property. The Property needs an accessible/visible setter.
 
 ## Example: Invalid Cases
 
@@ -18,6 +17,7 @@ public class STRDIAG006
 {
     // non existent setters count as non visible
     [DataMember(DataMemberMode.Assign)]
+    [DataMember(DataMemberMode.Assign)]
     public int Property1 { get; }
 
     [DataMember(DataMemberMode.Assign)]
@@ -31,11 +31,11 @@ public class STRDIAG006
 }
 ```
 
-## Example: Special Case internal
+## Example: Special Case `internal`
 
 > [!IMPORTANT]
 > To explicitly set the `DataMemberMode.Assign` the @Stride.Core.DataMemberAttribute has to be applied.
-> Internal visibility counts then as visible for the Serializers and becomes valid.
+> Internal visibility counts then as visible for the serializers and becomes valid.
 
 ```csharp
 using Stride.Core;
@@ -53,8 +53,7 @@ public class STRDIAG006
 
 ## Solution
 
-To resolve the warning, increase the accessibility of the Properties set to pulic/internal.
-Or remove the explicit `DataMemberMode.Assign`, this can result in the `DataMemberMode.Content`, if the Property is a non valuetype/string type.
+To resolve the warning, increase the accessibility of the properties set to `public`/`internal`. Or remove the explicit `DataMemberMode.Assign`, this can result in the `DataMemberMode.Content`, if the property is a non valuetype/string type.
 
 ## References
 

Diff for: en/diagnostics/STRDIAG007.md

@@ -4,8 +4,7 @@
 
 ## Explanation
 
-Delegates can't be serialized by the Serializers in Stride.
-So the @Stride.Core.DataMemberAttribute is always invalid on a delegate member in a type.
+Delegates can't be serialized by the serializers in Stride. Therefore, the @Stride.Core.DataMemberAttribute is always invalid when applied to a delegate member in a type.
 
 ## Example: Invalid Cases
 
@@ -26,7 +25,7 @@ public class STRDIAG007
 
 ## Solution
 
-To resolve the warning, remove the @Stride.Core.DataMemberAttribute .
+To resolve the warning, remove the @Stride.Core.DataMemberAttribute.
 
 ## References
 

Diff for: en/diagnostics/STRDIAG008.md

@@ -1,11 +1,10 @@
 # Diagnostics Warning STRDIAG008
 
-> Struct members with the 'fixed' Modifier are not supported as a Serialization target on member '{0}'..
+> Struct members with the 'fixed' Modifier are not supported as a Serialization target on member '{0}'.
 
 ## Explanation
 
-The Stride Serializers can't handle fixed members in structs.
-The @Stride.Core.DataMemberAttribute is always invalid on such a member.
+The Stride serializers can't handle `fixed` members in structs. The @Stride.Core.DataMemberAttribute is always invalid on such a member.
 
 ## Example: Invalid Cases
 
@@ -23,7 +22,7 @@ public unsafe struct STRDIAG008
 
 ## Solution
 
-To resolve the warning, remove the @Stride.Core.DataMemberAttribute .
+To resolve the warning, remove the @Stride.Core.DataMemberAttribute.
 
 ## References
 

Diff for: en/diagnostics/STRDIAG009.md

@@ -1,11 +1,10 @@
 # Diagnostics Warning STRDIAG009
 
-> The member '{0}' implements IDictionary<T,K> with an unsupported type for the key. Only primitive types ( like int,float,.. ) are supported or string or enums as the Dictionary Key in asset serialization. When used in other contexts the warning may not apply and can be suppressed."
+> The member '{0}' implements IDictionary<T,K> with an unsupported type for the key. Only primitive types ( like int,float,.. ) are supported or string or enums as the Dictionary Key in asset serialization. When used in other contexts the warning may not apply and can be suppressed.
 
 ## Explanation
 
-Per Default Stride Serializers only Support primitive types and string as a IDictionary Key.
-It is possible to make them supported, so this warning isn't fully accurate in every case.
+By default, Stride serializers only support primitive types and `string` as keys in an `IDictionary`. However, it is possible to extend this support, making the warning not entirely accurate in all cases.
 
 ## Example
 
@@ -29,9 +28,7 @@ public class STRDIAG009
 
 ## Solution
 
-To resolve the warning, remove the @Stride.Core.DataMemberAttribute .
-Or change the Key of the IDictionary to a supported type.
-Add a pragma Suppression in the IDE if it is a valid type.
+To resolve the warning, remove the @Stride.Core.DataMemberAttribute. Or change the key of the `IDictionary` to a supported type. Add a pragma Suppression in the IDE if it is a valid type.
 
 ## References
 

Diff for: en/diagnostics/index.md

@@ -2,8 +2,8 @@
 
 Some C# compiler errors have corresponding topics that explain why the error is generated, and, in some cases, how to fix the error. Use one of the following steps to see whether help is available for a particular error message.
 
-[Rule of Thumb Serialization](https://github.com/stride3d/stride-docs/blob/master/en/manual/scripts/serialization.md#rule-of-thumb)
+[Rule of Thumb Serialization](../manual/scripts/serialization.md#rule-of-thumb)
 
 > [!WARNING]
-> Note that diagnostic feature is experimental and may not work as expected.
-> Warnings may contain solutions that don't work yet.
+> Please note that this diagnostic feature is experimental and may not work as expected.
+> Warnings might include solutions that are not yet fully functional.

Diff for: en/diagnostics/toc.md

@@ -9,4 +9,4 @@
 # [STRDIAG006](STRDIAG006.md)
 # [STRDIAG007](STRDIAG007.md)
 # [STRDIAG008](STRDIAG008.md)
-# [STRDIAG009](STRDIAG009.md)
+# [STRDIAG009](STRDIAG009.md)