diff --git a/src/Sarif.Multitool/Rules/RuleResources.Designer.cs b/src/Sarif.Multitool/Rules/RuleResources.Designer.cs index 6dff33466..5ee908723 100644 --- a/src/Sarif.Multitool/Rules/RuleResources.Designer.cs +++ b/src/Sarif.Multitool/Rules/RuleResources.Designer.cs @@ -663,7 +663,9 @@ internal static string SARIF2013_ProvideEmbeddedFileContent_Note_Default_Text { } /// - /// Looks up a localized string similar to Including "dynamic content" (information that varies among results from the same rule) makes your messages more specific. It avoids the "wall of bugs" phenomenon, where hundreds of occurrences of the same message appear unapproachable.. + /// Looks up a localized string similar to Include "dynamic content" (information that varies among results from the same rule) to makes your messages more specific, and to avoid the "wall of bugs" phenomenon, where hundreds of occurrences of the same message appear unapproachable. + /// + ///This is part of a set of authoring practices that make your rule messages more readable, understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and 'SARIF2015.EnquoteDynamicMessageContent'.. /// internal static string SARIF2014_ProvideDynamicMessageContent_FullDescription_Text { get { @@ -672,7 +674,7 @@ internal static string SARIF2014_ProvideDynamicMessageContent_FullDescription_Te } /// - /// Looks up a localized string similar to {0}: In rule '{1}', the '{2}' property of the message with id '{3}' does not include any dynamic content. Dynamic content makes your messages more specific and avoids the "wall of bugs" phenomenon.. + /// Looks up a localized string similar to {0}: In rule '{1}', the message with id '{2}' does not include any dynamic content. Dynamic content makes your messages more specific and avoids the "wall of bugs" phenomenon, where hundreds of occurrences of the same message appear unapproachable.. /// internal static string SARIF2014_ProvideDynamicMessageContent_Note_Default_Text { get { @@ -681,7 +683,9 @@ internal static string SARIF2014_ProvideDynamicMessageContent_Note_Default_Text } /// - /// Looks up a localized string similar to Placing dynamic content in quotes sets it off from the static text, making it easier to spot. It's especially helpful when the dynamic content is a string that might contain spaces, and most especially when the string might be empty (and so would be invisible if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, even though English usage would require double quotes.. + /// Looks up a localized string similar to Place dynamic content in single quotes to set it off from the static text and to make it easier to spot. It's especially helpful when the dynamic content is a string that might contain spaces, and most especially when the string might be empty (and so would be invisible if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, even though US English usage would require double quotes. + /// + ///This is part of a set of authoring practices that make your rule messages more readable, [rest of string was truncated]";. /// internal static string SARIF2015_EnquoteDynamicMessageContent_FullDescription_Text { get { diff --git a/src/Sarif.Multitool/Rules/RuleResources.resx b/src/Sarif.Multitool/Rules/RuleResources.resx index adc3686a4..6175b41f6 100644 --- a/src/Sarif.Multitool/Rules/RuleResources.resx +++ b/src/Sarif.Multitool/Rules/RuleResources.resx @@ -323,13 +323,17 @@ When a result's 'message' object uses the 'id' and 'arguments' properties (which Placeholder_SARIF2013_ProvideEmbeddedFileContent_Note_Default_Text - Including "dynamic content" (information that varies among results from the same rule) makes your messages more specific. It avoids the "wall of bugs" phenomenon, where hundreds of occurrences of the same message appear unapproachable. + Include "dynamic content" (information that varies among results from the same rule) to makes your messages more specific, and to avoid the "wall of bugs" phenomenon, where hundreds of occurrences of the same message appear unapproachable. + +This is part of a set of authoring practices that make your rule messages more readable, understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and 'SARIF2015.EnquoteDynamicMessageContent'. - {0}: In rule '{1}', the '{2}' property of the message with id '{3}' does not include any dynamic content. Dynamic content makes your messages more specific and avoids the "wall of bugs" phenomenon. + {0}: In rule '{1}', the message with id '{2}' does not include any dynamic content. Dynamic content makes your messages more specific and avoids the "wall of bugs" phenomenon, where hundreds of occurrences of the same message appear unapproachable. - Placing dynamic content in quotes sets it off from the static text, making it easier to spot. It's especially helpful when the dynamic content is a string that might contain spaces, and most especially when the string might be empty (and so would be invisible if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, even though English usage would require double quotes. + Place dynamic content in single quotes to set it off from the static text and to make it easier to spot. It's especially helpful when the dynamic content is a string that might contain spaces, and most especially when the string might be empty (and so would be invisible if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, even though US English usage would require double quotes. + +This is part of a set of authoring practices that make your rule messages more readable, understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and 'SARIF2014.ProvideDynamicMessageContent'. {0}: In rule '{1}', the message with id '{2}' includes dynamic content that is not enclosed in single quotes. Enquoting dynamic content makes it easier to spot, and single quotes give a less cluttered appearance. diff --git a/src/Sarif.Multitool/Rules/SARIF2014.ProvideDynamicMessageContent.cs b/src/Sarif.Multitool/Rules/SARIF2014.ProvideDynamicMessageContent.cs index 8ec30e05e..8f20533d9 100644 --- a/src/Sarif.Multitool/Rules/SARIF2014.ProvideDynamicMessageContent.cs +++ b/src/Sarif.Multitool/Rules/SARIF2014.ProvideDynamicMessageContent.cs @@ -17,9 +17,13 @@ public class ProvideDynamicMessageContent : SarifValidationSkimmerBase public override string Id => RuleId.ProvideDynamicMessageContent; /// - /// Including "dynamic content" (information that varies among results from the same rule) - /// makes your messages more specific.It avoids the "wall of bugs" phenomenon, where hundreds - /// of occurrences of the same message appear unapproachable. + /// Include "dynamic content" (information that varies among results from the same rule) to + /// makes your messages more specific, and to avoid the "wall of bugs" phenomenon, where + /// hundreds of occurrences of the same message appear unapproachable. + /// + /// This is part of a set of authoring practices that make your rule messages more readable, + /// understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and + /// 'SARIF2015.EnquoteDynamicMessageContent'. /// public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = RuleResources.SARIF2014_ProvideDynamicMessageContent_FullDescription_Text }; @@ -75,9 +79,9 @@ private void AnalyzeMessageString(string ruleId, string messageString, string me if (!s_dynamicContentRegex.IsMatch(messageString)) { - // {0}: In rule '{1}', the '{2}' property of the message with id '{3}' does not include - // any dynamic content. Dynamic content makes your messages more specific and avoids the - // "wall of bugs" phenomenon. + // {0}: In rule '{1}', the message with id '{2}' does not include any dynamic content. + // Dynamic content makes your messages more specific and avoids the "wall of bugs" + // phenomenon, where hundreds of occurrences of the same message appear unapproachable. LogResult( pointer, nameof(RuleResources.SARIF2014_ProvideDynamicMessageContent_Note_Default_Text), diff --git a/src/Sarif.Multitool/Rules/SARIF2015.EnquoteDynamicMessageContent.cs b/src/Sarif.Multitool/Rules/SARIF2015.EnquoteDynamicMessageContent.cs index 6bfe8cb04..b72d0dd46 100644 --- a/src/Sarif.Multitool/Rules/SARIF2015.EnquoteDynamicMessageContent.cs +++ b/src/Sarif.Multitool/Rules/SARIF2015.EnquoteDynamicMessageContent.cs @@ -17,11 +17,15 @@ public class EnquoteDynamicMessageContent : SarifValidationSkimmerBase public override string Id => RuleId.EnquoteDynamicMessageContent; /// - /// Placing dynamic content in quotes sets it off from the static text, making it easier - /// to spot. It's especially helpful when the dynamic content is a string that might contain - /// spaces, and most especially when the string might be empty (and so would be invisible - /// if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, - /// even though English usage would require double quotes. + /// Place dynamic content in single quotes to set it off from the static text and to make it easier + /// to spot. It's especially helpful when the dynamic content is a string that might contain spaces, + /// and most especially when the string might be empty (and so would be invisible if it weren't for + /// the quotes). We recommend single quotes for a less cluttered appearance, even though US English + /// usage would require double quotes. + /// + /// This is part of a set of authoring practices that make your rule messages more readable, + /// understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and + /// 'SARIF2014.ProvideDynamicMessageContent'. /// public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = RuleResources.SARIF2015_EnquoteDynamicMessageContent_FullDescription_Text }; diff --git a/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2014.ProvideDynamicMessageContent_Invalid.sarif b/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2014.ProvideDynamicMessageContent_Invalid.sarif index f566e95c0..bfbc7727b 100644 --- a/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2014.ProvideDynamicMessageContent_Invalid.sarif +++ b/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2014.ProvideDynamicMessageContent_Invalid.sarif @@ -11,14 +11,14 @@ "id": "SARIF2014", "name": "ProvideDynamicMessageContent", "shortDescription": { - "text": "Including \"dynamic content\" (information that varies among results from the same rule) makes your messages more specific." + "text": "Include \"dynamic content\" (information that varies among results from the same rule) to makes your messages more specific, and to avoid the \"wall of bugs\" phenomenon, where hundreds of occurrences of the same message appear unapproachable." }, "fullDescription": { - "text": "Including \"dynamic content\" (information that varies among results from the same rule) makes your messages more specific. It avoids the \"wall of bugs\" phenomenon, where hundreds of occurrences of the same message appear unapproachable." + "text": "Include \"dynamic content\" (information that varies among results from the same rule) to makes your messages more specific, and to avoid the \"wall of bugs\" phenomenon, where hundreds of occurrences of the same message appear unapproachable.\r\n\r\nThis is part of a set of authoring practices that make your rule messages more readable, understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and 'SARIF2015.EnquoteDynamicMessageContent'." }, "messageStrings": { "Note_Default": { - "text": "{0}: In rule '{1}', the '{2}' property of the message with id '{3}' does not include any dynamic content. Dynamic content makes your messages more specific and avoids the \"wall of bugs\" phenomenon." + "text": "{0}: In rule '{1}', the message with id '{2}' does not include any dynamic content. Dynamic content makes your messages more specific and avoids the \"wall of bugs\" phenomenon, where hundreds of occurrences of the same message appear unapproachable." } }, "helpUri": "http://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html" diff --git a/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2015.EnquoteDynamicMessageContent_Invalid.sarif b/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2015.EnquoteDynamicMessageContent_Invalid.sarif index 6f8884e38..d6c0e64f9 100644 --- a/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2015.EnquoteDynamicMessageContent_Invalid.sarif +++ b/src/Test.FunctionalTests.Sarif/TestData/Multitool/ValidateCommand/ExpectedOutputs/SARIF2015.EnquoteDynamicMessageContent_Invalid.sarif @@ -11,10 +11,10 @@ "id": "SARIF2015", "name": "EnquoteDynamicMessageContent", "shortDescription": { - "text": "Placing dynamic content in quotes sets it off from the static text, making it easier to spot." + "text": "Place dynamic content in single quotes to set it off from the static text and to make it easier to spot." }, "fullDescription": { - "text": "Placing dynamic content in quotes sets it off from the static text, making it easier to spot. It's especially helpful when the dynamic content is a string that might contain spaces, and most especially when the string might be empty (and so would be invisible if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, even though English usage would require double quotes." + "text": "Place dynamic content in single quotes to set it off from the static text and to make it easier to spot. It's especially helpful when the dynamic content is a string that might contain spaces, and most especially when the string might be empty (and so would be invisible if it weren't for the quotes). We recommend single quotes for a less cluttered appearance, even though US English usage would require double quotes.\r\n\r\nThis is part of a set of authoring practices that make your rule messages more readable, understandable, and actionable. See also 'SARIF2001.TerminateMessagesWithPeriod' and 'SARIF2014.ProvideDynamicMessageContent'." }, "messageStrings": { "Note_Default": {