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)