Updated issue documentation. (#256)

* Parsing issues updated.

* Updating the error docs to give them more information.

* Convert all the .md files to UTF8 to be more friendly with tools like Github.

* PR CR feedback.

* PR CR feedback.

source/Issues/IssuesClassGenerator.t4

@@ -84,8 +84,20 @@ namespace <#=namespaceName#>
         var parameterList = string.Join(", ", parameters);
         var hasParameters = parameters.Any();
 
+        // Check for the issue being deprecated. Deprecated issues
+        // do not generate any code.
+        var isDeprecated = mdCommentLines.Any(content => content == "deprecated");
+
         WriteLine("");
-        WriteLine($"        internal void {name}({parameterList}) => Report(\"{issueId}\", {(hasParameters ? "$" : "")}\"{text}\");");
+        if (isDeprecated)
+        {
+            WriteLine($"        // {issueId} has been deprecated.");
+            WriteLine($"        // Was: {text}");
+        }
+        else 
+        {
+            WriteLine($"        internal void {name}({parameterList}) => Report(\"{issueId}\", {(hasParameters ? "$" : "")}\"{text}\");");
+        }
     }
 #>
 

source/Issues/LP0008.md

@@ -1,14 +1,13 @@
-
-[comment]: # (name:LayerEffectsIsNotSupported)
+[comment]: # (name:LayerEffectsIsNotSupported)
 [comment]: # (text:{layer} has layer effects, which is not supported.)
 
 # Lottie-Windows Warning LP0008
 
-<!-- description -->
+The Lottie file contains layer effects. Layer effects are currently not supported.
 
 ## Remarks
+Lottie-Windows does not currently support layer effects. It may be possible to work around this by modifying your After Effects project to avoid the use of layer effects.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LP0009.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:Mattes)
 [comment]: # (text:Mattes.)
 
 # Lottie-Windows Warning LP0009
 
-<!-- description -->
+Mattes are not supported in this version of Lottie-Windows.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LP0012.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:UnexpectedShapeContentType)
 [comment]: # (text:Unexpected shape content type: {type}.)
 
 # Lottie-Windows Warning LP0012
 
-<!-- description -->
+A Lottie shape has an unexpected content type.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LP0013.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:GradientStrokes)
 [comment]: # (text:Gradient strokes.)
 
 # Lottie-Windows Warning LP0013
 
-<!-- description -->
+Gradient strokes are not supported in this version of Lottie-Windows.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0003.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:AnimationMultiplicationIsNotSupported)
 [comment]: # (text:Multiplication of two or more animated values is not supported.)
 
 # Lottie-Windows Warning LT0003
 
-<!-- description -->
+Multiplication of two or more animated values is not supported.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0004.md

@@ -1,14 +1,18 @@
-
-[comment]: # (name:BlendModeNotNormal)
+[comment]: # (name:BlendModeNotNormal)
 [comment]: # (text:{layer} has {blendMode} as blend mode. Only Normal is supported.)
 
 # Lottie-Windows Warning LT0004
 
-<!-- description -->
+A layer has an unsupported blend mode.
 
 ## Remarks
 
-<!-- notes  -->
+Lottie-Windows currently supports only the Normal blend mode. Other blend modes will
+be treated as Normal.
+
+If support for this feature is important for your scenario please provide feedback
+by raising it as an issue [here](https://github.com/windows-toolkit/Lottie-Windows/issues).
+
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0007.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:GradientStrokeIsNotSupported)
 [comment]: # (text:{linearOrRadial} gradient stroke with {combination} is not supported.)
 
 # Lottie-Windows Warning LT0007
 
-<!-- description -->
+Some gradient strokes are not supported.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0009.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:ImageLayerIsNotSupported)
 [comment]: # (text:Image layers are not supported.)
 
 # Lottie-Windows Warning LT0009
 
-<!-- description -->
+Images layers are not supported.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0015.md

@@ -1,15 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:OpacityAndColorAnimatedTogetherIsNotSupported)
 [comment]: # (text:Opacity and color animated at the same time is not supported.)
 
 # Lottie-Windows Warning LT0015
 
-<!-- description -->
+Shapes that have both animated opacity and animated color are not supported.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0026.md

@@ -1,15 +1,12 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:MultipleShapeMasksIsNotSupported)
 [comment]: # (text:Mask with multiple shapes is not supported.)
 
 # Lottie-Windows Warning LT0026
 
-<!-- description -->
-
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0030.md

@@ -1,15 +1,17 @@
-
-[comment]: # (name:ImageFileRequired)
+[comment]: # (name:ImageFileRequired)
 [comment]: # (text:Image file required at {filePath}.)
 
 # Lottie-Windows Warning LT0030
 
-<!-- description -->
+The Lottie file contains a reference to an image file at the given file path. Currently
+Lottie-Windows only supports images that are embedded in the Lottie file.
 
 ## Remarks
-If you are hitting this issue on your Lottie file, it means your Lottie file references an image file. This scenario is not yet supported.
+Lottie files that reference images in other files are not currently supported by Lottie-Windows.
+
+If support for image files is important for your scenario please provide feedback
+by raising it as an issue [here](https://github.com/windows-toolkit/Lottie-Windows/issues).
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0031.md

@@ -1,16 +1,15 @@
+[comment]: # (deprecated)
 [comment]: # (name:MattesAreNotSupported)
 [comment]: # (text:Mattes are not supported.)
 
 # Lottie-Windows Warning LT0031
 
-<!-- description -->
 Mattes are not supported.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)
-* [Questions and feedback via Github](https://github.com/windows-toolkit/Lottie-Windows/issues)
+* [Questions and feedback via Github](https://github.com/windows-toolkit/Lottie-Windows/issues)

source/Issues/LT0032.md

@@ -1,16 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:MaskModesDoNotMatch)
 [comment]: # (text:A multiple shape mask is only supported if the shapes all have the same mode.)
 
 # Lottie-Windows Warning LT0032
 
-<!-- description -->
 A multiple shape mask is only supported if the shapes all have the same mode.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0033.md

@@ -1,16 +1,14 @@
-
+[comment]: # (deprecated)
 [comment]: # (name:MasksNotSupported)
 [comment]: # (text:Masks are not supported.)
 
 # Lottie-Windows Warning LT0033
 
-<!-- description -->
 Masks are not supported.
 
 ## Remarks
-This issue has been deprecated. Please upgrade to a newer version of Lottie-Windows.
+This issue does not apply to the latest version. Please upgrade to a newer version of Lottie-Windows.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0034.md

@@ -1,16 +1,19 @@
-
-[comment]: # (name:UapVersionNotSupported)
+[comment]: # (name:UapVersionNotSupported)
 [comment]: # (text:{versionDependentFeature} requires a UAP version of at least {optimalUapVersion}.)
 
 # Lottie-Windows Warning LT0034
 
-<!-- description -->
 The specified UAP version is missing some functionality required by the Lottie animation.
 The animation will still play, but may look incorrect.
 
 ## Remarks
+Lottie-Windows generates code to run on the Universal App Platform. Some earlier versions of
+this platform lack support for some Lottie features. You may be able to work around the
+lack of support by modifying the After Effects project to remove the use of the unsupported
+feature.
+
+You can specify the minimum UAP version required when generating code with LottieGen.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/Issues/LT0035.md

@@ -1,10 +1,8 @@
-
-[comment]: # (name:ThemePropertyValuesAreInconsistent)
+[comment]: # (name:ThemePropertyValuesAreInconsistent)
 [comment]: # (text:Theme property "{themePropertyName}" has more than one value. Using {chosenValue} in place of {requestedValue}.)
 
 # Lottie-Windows Warning LT0035
 
-<!-- description -->
 Theme properties are an extension to Lottie that enable property values such as colors
 to be updated at runtime. At runtime every element in a Lottie file that is bound to a
 particular theme property name will get the same value, even if the values in the Lottie
@@ -18,7 +16,6 @@ The default value chosen for a theme property is the value that is set in the Lo
 If there are multiple values set for the same theme property name, the translator will
 choose one of those values as the default.
 
-<!-- notes  -->
 ## Resources
 
 * [Lottie-Windows repository](https://aka.ms/lottie)

source/LottieReader/Serialization/ParsingIssues.cs

@@ -32,7 +32,8 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieData.Serialization
 
         internal (string Code, string Description)[] GetIssues() => _issues.ToArray();
 
-        internal void FailedToParseJson(string message) => Report("LP0001", $"Failed to parse JSON. {message}.");
+        // LP0001 has been deprecated.
+        // Was: Failed to parse JSON. {message}.
 
         internal void FatalError(string message) => Report("LP0002", $"Fatal error: {message}.");
 
@@ -44,15 +45,19 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieData.Serialization
 
         internal void LayerEffectsIsNotSupported(string layer) => Report("LP0008", $"{layer} has layer effects, which is not supported.");
 
-        internal void Mattes() => Report("LP0009", "Mattes.");
+        // LP0009 has been deprecated.
+        // Was: Mattes.
 
         internal void TimeRemappingOfPreComps() => Report("LP0011", "Time remapping of precomp layers.");
 
-        internal void UnexpectedShapeContentType(string type) => Report("LP0012", $"Unexpected shape content type: {type}.");
+        // LP0012 has been deprecated.
+        // Was: Unexpected shape content type: {type}.
 
-        internal void GradientStrokes() => Report("LP0013", "Gradient strokes.");
+        // LP0013 has been deprecated.
+        // Was: Gradient strokes.
 
-        internal void PolystarAnimation(string property) => Report("LP0014", $"Polystar {property} animation.");
+        // LP0014 has been deprecated.
+        // Was: Polystar {property} animation.
 
         internal void Expressions() => Report("LP0015", "Expressions.");
 

source/LottieReader/Serialization/ShapeLayerContents.cs

@@ -324,55 +324,21 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieData.Serialization
             var direction = obj.BoolPropertyOrNull("d") == true;
 
             var points = ReadAnimatableFloat(obj.ObjectPropertyOrNull("pt"));
-            if (points.IsAnimated)
-            {
-                _issues.PolystarAnimation("points");
-            }
-
             var position = ReadAnimatableVector3(obj.ObjectPropertyOrNull("p"));
-            if (position.IsAnimated)
-            {
-                _issues.PolystarAnimation("position");
-            }
-
             var rotation = ReadAnimatableFloat(obj.ObjectPropertyOrNull("r"));
-            if (rotation.IsAnimated)
-            {
-                _issues.PolystarAnimation("rotation");
-            }
-
             var outerRadius = ReadAnimatableFloat(obj.ObjectPropertyOrNull("or"));
-            if (outerRadius.IsAnimated)
-            {
-                _issues.PolystarAnimation("outer radius");
-            }
-
             var outerRoundedness = ReadAnimatableFloat(obj.ObjectPropertyOrNull("os"));
-            if (outerRoundedness.IsAnimated)
-            {
-                _issues.PolystarAnimation("outer roundedness");
-            }
+
+            var polystarType = SyToPolystarType(obj.DoublePropertyOrNull("sy")) ?? Polystar.PolyStarType.Polygon;
 
             Animatable<double> innerRadius;
             Animatable<double> innerRoundedness;
 
-            var polystarType = SyToPolystarType(obj.DoublePropertyOrNull("sy")) ?? Polystar.PolyStarType.Polygon;
-
             switch (polystarType)
             {
                 case Polystar.PolyStarType.Star:
                     innerRadius = ReadAnimatableFloat(obj.ObjectPropertyOrNull("ir"));
-                    if (innerRadius.IsAnimated)
-                    {
-                        _issues.PolystarAnimation("inner radius");
-                    }
-
                     innerRoundedness = ReadAnimatableFloat(obj.ObjectPropertyOrNull("is"));
-                    if (innerRoundedness.IsAnimated)
-                    {
-                        _issues.PolystarAnimation("inner roundedness");
-                    }
-
                     break;
 
                 default:

source/LottieToWinComp/TranslationIssues.cs

@@ -36,7 +36,8 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieToWinComp
 
         internal void AnimatedTrimOffsetWithStaticTrimOffsetIsNotSupported() => Report("LT0002", "Animated trim offset with static trim offset is not supported.");
 
-        internal void AnimationMultiplicationIsNotSupported() => Report("LT0003", "Multiplication of two or more animated values is not supported.");
+        // LT0003 has been deprecated.
+        // Was: Multiplication of two or more animated values is not supported.
 
         internal void BlendModeNotNormal(string layer, string blendMode) => Report("LT0004", $"{layer} has {blendMode} as blend mode. Only Normal is supported.");
 
@@ -44,9 +45,11 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieToWinComp
 
         internal void GradientFillIsNotSupported(string linearOrRadial, string combination) => Report("LT0006", $"{linearOrRadial} gradient fill with {combination} is not supported.");
 
-        internal void GradientStrokeIsNotSupported(string linearOrRadial, string combination) => Report("LT0007", $"{linearOrRadial} gradient stroke with {combination} is not supported.");
+        // LT0007 has been deprecated.
+        // Was: {linearOrRadial} gradient stroke with {combination} is not supported.
 
-        internal void ImageLayerIsNotSupported() => Report("LT0009", "Image layers are not supported.");
+        // LT0009 has been deprecated.
+        // Was: Image layers are not supported.
 
         internal void MergingALargeNumberOfShapesIsNotSupported() => Report("LT0010", "Merging a large number of shape is not supported.");
 
@@ -58,7 +61,8 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieToWinComp
 
         internal void MultipleTrimPathsIsNotSupported() => Report("LT0014", "Multiple trim paths is not supported.");
 
-        internal void OpacityAndColorAnimatedTogetherIsNotSupported() => Report("LT0015", "Opacity and color animated at the same time is not supported.");
+        // LT0015 has been deprecated.
+        // Was: Opacity and color animated at the same time is not supported.
 
         internal void PathWithRoundedCornersIsNotSupported() => Report("LT0016", "Path with rounded corners is not supported.");
 
@@ -68,9 +72,9 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieToWinComp
 
         internal void TextLayerIsNotSupported() => Report("LT0019", "Text layer is not supported.");
 
-        internal void ThreeDIsNotSupported() => Report("LT0020", "3d composition is not supported.");
+        internal void ThreeDIsNotSupported() => Report("LT0020", "3D composition is not supported.");
 
-        internal void ThreeDLayerIsNotSupported() => Report("LT0021", "3d layer is not supported.");
+        internal void ThreeDLayerIsNotSupported() => Report("LT0021", "3D layer is not supported.");
 
         internal void TimeStretchIsNotSupported() => Report("LT0022", "Time stretch is not supported.");
 
@@ -80,7 +84,8 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieToWinComp
 
         internal void MaskWithAlphaIsNotSupported() => Report("LT0025", "Mask with alpha value other than 1 is not supported.");
 
-        internal void MultipleShapeMasksIsNotSupported() => Report("LT0026", "Mask with multiple shapes is not supported.");
+        // LT0026 has been deprecated.
+        // Was: Mask with multiple shapes is not supported.
 
         internal void CombiningMultipleShapesIsNotSupported() => Report("LT0027", "Combining multiple shapes is not supported.");
 
@@ -90,11 +95,14 @@ namespace Microsoft.Toolkit.Uwp.UI.Lottie.LottieToWinComp
 
         internal void ImageFileRequired(string filePath) => Report("LT0030", $"Image file required at {filePath}.");
 
-        internal void MattesAreNotSupported() => Report("LT0031", "Mattes are not supported.");
+        // LT0031 has been deprecated.
+        // Was: Mattes are not supported.
 
-        internal void MaskModesDoNotMatch() => Report("LT0032", "A multiple shape mask is only supported if the shapes all have the same mode.");
+        // LT0032 has been deprecated.
+        // Was: A multiple shape mask is only supported if the shapes all have the same mode.
 
-        internal void MasksNotSupported() => Report("LT0033", "Masks are not supported.");
+        // LT0033 has been deprecated.
+        // Was: Masks are not supported.
 
         internal void UapVersionNotSupported(string versionDependentFeature, string optimalUapVersion) => Report("LT0034", $"{versionDependentFeature} requires a UAP version of at least {optimalUapVersion}.");