Merge pull request #168 from stride3d/master

Testing recent updates in staging

en/diagnostics/STRDIAG000.md

@@ -0,0 +1,56 @@
+# Diagnostics Warning STRDIAG000
+
+> There is an Attribute Contradiction on '{0}' Member. `[DataMemberIgnore]` Attribute on a `[DataMember]` is not supported.
+> Except if it has also `[DataMemberUpdatable]` Attribute.
+
+## 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.
+
+## Example: Invalid cases
+
+The following example generates STRDIAG000 on each property:
+
+```csharp
+// STRDIAG000.cs
+using Stride.Core;
+
+public class STRDIAG000
+{
+    [DataMember]
+    [DataMemberIgnore]
+    public int Value { get; set; }
+
+    [DataMember]
+    [DataMemberIgnore]
+    public int Value;
+}
+```
+
+## Example: Special Case `DataMemberUpdatable`
+
+> [!IMPORTANT]
+> There is a special case if the @Stride.Updater.DataMemberUpdatableAttribute is applied.
+> This Attribute negates the @Stride.Core.DataMemberIgnoreAttribute for the binary Serializer, so it becomes valid again.
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG000
+{
+    [DataMember]
+    [DataMemberIgnore]
+    [DataMemberUpdatable]
+    public int Value { get; set; }
+}
+```
+
+## 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.
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG001.md

@@ -0,0 +1,40 @@
+# Diagnostics Warning STRDIAG001
+
+> The `[DataContract]` is not valid for the type '{0}'. Expected is a public/internal Accessor.
+
+## Explanation
+
+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
+
+The following example generates STRDIAG001:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG001
+{
+    [DataContract]
+    private class InnerClass { }
+}
+```
+
+## Example: file scoped class
+
+```csharp
+using Stride.Core;
+
+[DataContract]
+file class STRDIAG001
+{
+}
+```
+
+## Solution
+
+To resolve the warning, increase the accessibility of the type to pulic/internal or remove the @Stride.CoreDataContractAttribute .
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG002.md

@@ -0,0 +1,31 @@
+# Diagnostics Warning STRDIAG002
+
+> The 'DataMemberMode.Content' is not valid for the member '{0}'.
+> Only mutable reference types are supported for 'DataMemberMode.Content' Mode members.
+
+## 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.
+
+## Example
+
+The following example generates STRDIAG002 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG002
+{
+    [DataMember(DataMemberMode.Content)]
+    public int Value { get; set;}
+
+    [DataMember(DataMemberMode.Content)]
+    public string Value;
+}
+```
+
+## Solution
+
+To resolve the warning, pick either a reference type for the member or use `DataMemberMode.Assign` for Immutable types.

en/diagnostics/STRDIAG003.md

@@ -0,0 +1,33 @@
+# 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.
+
+## 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.
+
+## Example
+
+The following example generates STRDIAG003 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG003
+{
+    [DataMember]
+    private int Value { get; set;}
+
+    [DataMember]
+    protected string Value;
+    
+    [DataMember]
+    private protected string Value;
+}
+```
+
+## Solution
+
+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

@@ -0,0 +1,66 @@
+# Diagnostics Warning STRDIAG004
+
+> 1. The property '{0}' with `[DataMember]` does not have a getter which is required for serialization.
+> 2. The property '{0}' with `[DataMember]` does not have an accessible getter which is required for serialization. A public/internal/internal protected getter is expected.
+
+## 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.
+
+## Example
+
+The following example generates STRDIAG004 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG004
+{
+    // throws Diagnostics message 1
+    [DataMember]
+    public int Value { set;}
+
+    // throws Diagnostics message 2
+    [DataMember]
+    public string Value { private get; set; }
+
+    // throws Diagnostics message 2 
+    [DataMember]
+    public string Value { protected get; set; }
+}
+```
+
+> [!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.
+
+```csharp
+// STRDIAG000.cs
+using Stride.Core;
+
+public class STRDIAG004
+{
+    // will throw STRDIAG004
+    public int Value { internal get; set;}
+
+    // will throw STRDIAG004
+    public int Value { internal protected get; set;}
+
+    // won't throw STRDIAG004
+    [DataMember]
+    public string Value { internal get; set; }
+    
+    // won't throw STRDIAG004
+    [DataMember]
+    public string Value { internal protected get; set; }
+}
+```
+
+## 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 2, increase the Accessibility of the property getter to public/internal/internal protected Accessibility or remove the @Stride.Core.DataMemberAttribute .

en/diagnostics/STRDIAG005.md

@@ -0,0 +1,30 @@
+# Diagnostics Warning STRDIAG005
+
+> The `[DataMember]` Attribute is applied to a read-only member '{0}' with a non supported type. Only mutable reference types are supported for read-only members.
+
+## Explanation
+
+Having no set possibility automatically lets the serializers automatically use the `DataMemberMode.Content.`
+For immutable types the `DataMemberMode.Content` is never valid.
+Immutable types in this context are none reference types and string.
+
+## Example
+
+The following example generates STRDIAG005 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG005
+{
+    [DataMember]
+    public readonly int Value;
+    [DataMember]
+    public string Value { get; }
+}
+```
+
+## 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.

en/diagnostics/STRDIAG006.md

@@ -0,0 +1,61 @@
+# Diagnostics Warning STRDIAG006
+
+> 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.
+
+## Example: Invalid Cases
+
+The following example generates STRDIAG006:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG006
+{
+    // non existent setters count as non visible
+    [DataMember(DataMemberMode.Assign)]
+    public int Property1 { get; }
+
+    [DataMember(DataMemberMode.Assign)]
+    public int Property2 { get; private set; }
+    
+    [DataMember(DataMemberMode.Assign)]
+    public int Property3 { get; protected set; }
+    
+    [DataMember(DataMemberMode.Assign)]
+    public int Property4 { get; private protected set; }
+}
+```
+
+## 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.
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG006
+{
+    // non existent setters count as non visible
+    [DataMember(DataMemberMode.Assign)]
+    public int Property1 { get; internal set; }
+
+    [DataMember(DataMemberMode.Assign)]
+    public int Property2 { get; internal protected set; }
+}
+```
+
+## 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.
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG007.md

@@ -0,0 +1,33 @@
+# Diagnostics Warning STRDIAG007
+
+> Invalid `[DataMember]` Attribute on the member '{0}'. A Delegate is not serializable.
+
+## 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.
+
+## Example: Invalid Cases
+
+The following example generates STRDIAG007:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG007
+{
+    [DataMember]
+    public Action SomeDelegate;
+
+    [DataMember]
+    public Action SomeDelegate2 { get; set; }
+}
+```
+
+## Solution
+
+To resolve the warning, remove the @Stride.Core.DataMemberAttribute .
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG008.md

@@ -0,0 +1,30 @@
+# Diagnostics Warning STRDIAG008
+
+> 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.
+
+## Example: Invalid Cases
+
+The following example generates STRDIAG008:
+
+```csharp
+using Stride.Core;
+
+public unsafe struct STRDIAG008
+{
+    [DataMember]
+    public fixed byte Value[10];
+}
+```
+
+## Solution
+
+To resolve the warning, remove the @Stride.Core.DataMemberAttribute .
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG009.md

@@ -0,0 +1,38 @@
+# 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."
+
+## 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.
+
+## Example
+
+The following example generates STRDIAG009:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG009
+{
+    [DataMember]
+    public Dictionary<ClassType, AnyType>
+
+    [DataMember]
+    public Dictionary<StructType, AnyType>
+
+    [DataMember]
+    public Dictionary<InterfaceType, AnyType>
+}
+```
+
+## 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.
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/index.md

@@ -2,5 +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)
+
 > [!WARNING]
-> Note that diagnostic feature is experimental and may not work as expected.
+> Note that diagnostic feature is experimental and may not work as expected.
+> Warnings may contain solutions that don't work yet.

en/diagnostics/strd001.md

@@ -1,54 +0,0 @@
-# Diagnostics Warning STRD001
-
-An Array must have a public/internal getter for Serialization.
-
-## Example
-
-The following example generates STRD001:
-
-```csharp
-// STRD001.cs
-// compile with: /W:2
-public class Program
-{
-    public static void Main()
-    {
-        goto lab1;
-        {
-            // The following statements cannot be reached:
-            int i = 9;   // STRD001
-            i++;
-        }
-    lab1:
-        {
-        }
-    }
-}
-
-```
-
-Another common example where this error is generated is as follows:
-
-```csharp
-public static class Class1
-{
-    public static string Method1()
-    {
-        string x = "a";
-        switch (x)
-        {
-            case "a":
-                return "a";
-                break;          // CS0162
-        }
-        return "";
-    }
-}
-```
-
-The `break` statement cannot be reached because it occurs after the `return` statement. The `return` statement ends the enclosing `case` branch.
-
-## See also
-
-- [C# Compiler Options](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/)
-- [C# Compiler Errors](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/)

en/diagnostics/strd002.md

@@ -1,54 +0,0 @@
-# Diagnostics Warning STRD002
-
-A collection must have a public/internal getter for Serialization.
-
-## Example
-
-The following example generates STRD001:
-
-```csharp
-// STRD001.cs
-// compile with: /W:2
-public class Program
-{
-    public static void Main()
-    {
-        goto lab1;
-        {
-            // The following statements cannot be reached:
-            int i = 9;   // STRD001
-            i++;
-        }
-    lab1:
-        {
-        }
-    }
-}
-
-```
-
-Another common example where this error is generated is as follows:
-
-```csharp
-public static class Class1
-{
-    public static string Method1()
-    {
-        string x = "a";
-        switch (x)
-        {
-            case "a":
-                return "a";
-                break;          // CS0162
-        }
-        return "";
-    }
-}
-```
-
-The `break` statement cannot be reached because it occurs after the `return` statement. The `return` statement ends the enclosing `case` branch.
-
-## See also
-
-- [C# Compiler Options](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/)
-- [C# Compiler Errors](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/)

en/diagnostics/strd003.md

@@ -1,56 +0,0 @@
-# Diagnostics Warning STRD003
-
-- A property must have a public/internal getter.
-- A property must be set during instantiation, then no public setter would be valid.
-- Or it must have a public setter else.
-
-## Example
-
-The following example generates STRD001:
-
-```csharp
-// STRD001.cs
-// compile with: /W:2
-public class Program
-{
-    public static void Main()
-    {
-        goto lab1;
-        {
-            // The following statements cannot be reached:
-            int i = 9;   // STRD001
-            i++;
-        }
-    lab1:
-        {
-        }
-    }
-}
-
-```
-
-Another common example where this error is generated is as follows:
-
-```csharp
-public static class Class1
-{
-    public static string Method1()
-    {
-        string x = "a";
-        switch (x)
-        {
-            case "a":
-                return "a";
-                break;          // CS0162
-        }
-        return "";
-    }
-}
-```
-
-The `break` statement cannot be reached because it occurs after the `return` statement. The `return` statement ends the enclosing `case` branch.
-
-## See also
-
-- [C# Compiler Options](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/)
-- [C# Compiler Errors](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/)

en/diagnostics/strd004.md

@@ -1,54 +0,0 @@
-# Diagnostics Warning STRD004
-
-For <see cref="System.Collections.Generic.Dictionary{TKey, TValue}"/> the only valid Keys are primitive Types. All complex types like custom structs, objects are not allowed.
-
-## Example
-
-The following example generates STRD001:
-
-```csharp
-// STRD001.cs
-// compile with: /W:2
-public class Program
-{
-    public static void Main()
-    {
-        goto lab1;
-        {
-            // The following statements cannot be reached:
-            int i = 9;   // STRD001
-            i++;
-        }
-    lab1:
-        {
-        }
-    }
-}
-
-```
-
-Another common example where this error is generated is as follows:
-
-```csharp
-public static class Class1
-{
-    public static string Method1()
-    {
-        string x = "a";
-        switch (x)
-        {
-            case "a":
-                return "a";
-                break;          // CS0162
-        }
-        return "";
-    }
-}
-```
-
-The `break` statement cannot be reached because it occurs after the `return` statement. The `return` statement ends the enclosing `case` branch.
-
-## See also
-
-- [C# Compiler Options](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/)
-- [C# Compiler Errors](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/)

en/diagnostics/strd007.md

@@ -1,54 +0,0 @@
-# Diagnostics Warning STRD007
-
-It's invalid to DataMember a private property. Also its invalid to DataMember a property which has DataMemberIgnore.
-
-## Example
-
-The following example generates STRD001:
-
-```csharp
-// STRD001.cs
-// compile with: /W:2
-public class Program
-{
-    public static void Main()
-    {
-        goto lab1;
-        {
-            // The following statements cannot be reached:
-            int i = 9;   // STRD001
-            i++;
-        }
-    lab1:
-        {
-        }
-    }
-}
-
-```
-
-Another common example where this error is generated is as follows:
-
-```csharp
-public static class Class1
-{
-    public static string Method1()
-    {
-        string x = "a";
-        switch (x)
-        {
-            case "a":
-                return "a";
-                break;          // CS0162
-        }
-        return "";
-    }
-}
-```
-
-The `break` statement cannot be reached because it occurs after the `return` statement. The `return` statement ends the enclosing `case` branch.
-
-## See also
-
-- [C# Compiler Options](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/)
-- [C# Compiler Errors](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/)

en/diagnostics/toc.md

@@ -1,7 +1,12 @@
 # [Diagnostics](index.md)
 
-# [STRD001](strd001.md)
-# [STRD002](strd002.md)
-# [STRD003](strd003.md)
-# [STRD004](strd004.md)
-# [STRD007](strd007.md)
+# [STRDIAG000](STRDIAG000.md)
+# [STRDIAG001](STRDIAG001.md)
+# [STRDIAG002](STRDIAG002.md)
+# [STRDIAG003](STRDIAG003.md)
+# [STRDIAG004](STRDIAG004.md)
+# [STRDIAG005](STRDIAG005.md)
+# [STRDIAG006](STRDIAG006.md)
+# [STRDIAG007](STRDIAG007.md)
+# [STRDIAG008](STRDIAG008.md)
+# [STRDIAG009](STRDIAG009.md)

en/manual/game-studio/manage-entities.md

@@ -101,4 +101,3 @@ You can change the snap values for each gizmo in the scene view toolbar. Snap va
 * [Navigate in the Scene Editor](navigate-in-the-scene-editor.md)
 * [Load scenes](load-scenes.md)
 * [Add entities](add-entities.md)
-* [Manage entities](manage-entities.md)