Merge pull request stride3d#169 from VaclavElias/master

Diagnostics docs content improvements

Author: VaclavElias

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) {

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)

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
 

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.

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.

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 .

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.

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
 

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
 

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