From 9e56128498c2b60fe5791b61f5603145773a0116 Mon Sep 17 00:00:00 2001 From: Erik Krogh Kristensen Date: Fri, 16 Sep 2022 11:46:06 +0200 Subject: [PATCH] apply suggestions from doc review Co-authored-by: hubwriter --- docs/query-metadata-style-guide.md | 4 ++-- ql/ql/src/queries/style/AlertMessage.ql | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/query-metadata-style-guide.md b/docs/query-metadata-style-guide.md index 478bfea9bd6..20af4c12f3e 100644 --- a/docs/query-metadata-style-guide.md +++ b/docs/query-metadata-style-guide.md @@ -182,9 +182,9 @@ The select clause of each alert query defines the alert message that is displaye * If a reference to the current location can't be avoided use "this location" instead of "here". For example, `Bad thing at this location.` is preferable to `Bad thing here.`. This avoids the "click here" anti-pattern. * Where you reference another program element, link to it if possible using a substitution (`$@`). Links should be used inline in the sentence, rather than as parenthesised lists or appositions. * When a message contains multiple links, construct a sentence that has the most variable link (that is, the link with most targets) last. For further information, see [Defining the results of a query](https://codeql.github.com/docs/writing-codeql-queries/defining-the-results-of-a-query/). -* Make link texts as concise and precise as possible. E.g. avoid starting a link text with an indefinite article (a, an). For example `Path construction depends on a [user-provided value]` is preferable to `Path construction depends on [a user-provided value]`. (Where the square brackets indicate a link.) See [the W3C guide on link texts](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) for further information. +* Make link text as concise and precise as possible. For example, avoid starting a link text with an indefinite article (a, an). `Path construction depends on a [user-provided value]` is preferable to `Path construction depends on [a user-provided value]`. (Where the square brackets indicate a link.) See [the W3C guide on link texts](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) for further information. * For path queries, if possible, try to follow the template: `This path depends on a [user-provided value].`, or alternatively (if the first option doesn't work) `[User-provided value] flows to this location and is used in a path.`. -* Taint tracking queries generally have that a sink "depends on" the source, and dataflow queries generally have a source that "flows to" the sink. +* Taint tracking queries generally have a sink that "depends on" the source, and dataflow queries generally have a source that "flows to" the sink. For examples of select clauses and alert messages, see the query source files at the following pages: diff --git a/ql/ql/src/queries/style/AlertMessage.ql b/ql/ql/src/queries/style/AlertMessage.ql index f496a42cba1..8be6f0f2d99 100644 --- a/ql/ql/src/queries/style/AlertMessage.ql +++ b/ql/ql/src/queries/style/AlertMessage.ql @@ -40,9 +40,9 @@ private AstNode getSelectPart(Select sel, int index) { } /** - * Gets a string element that is the last part of the message, that doesn't end with a full stop. + * Gets a string element that is the last part of the message, that doesn't end with a period. * - * E.g. + * For example: * ```CodeQL * select foo(), "This is a description" // <- bad * @@ -63,7 +63,7 @@ String shouldHaveFullStop(Select sel) { /** * Gets a string element that is the first part of the message, that starts with a lower case letter. * - * E.g. + * For example: * ```CodeQL * select foo(), "this is a description." // <- bad * @@ -83,7 +83,7 @@ String shouldStartCapital(Select sel) { /** * Gets a string element that is used in a message that contains "here" or "this location". * - * E.g. + * For example: * ```CodeQL * select foo(), "XSS happens here from using a unsafe value." // <- bad * @@ -101,7 +101,7 @@ String avoidHere(string part) { /** * Avoid using an indefinite article ("a" or "an") in a link text. * - * E.g. + * For example: * ```CodeQL * select foo(), "XSS from $@", val, "an unsafe value." // <- bad * @@ -119,7 +119,7 @@ String avoidArticleInLinkText(Select sel) { /** * Don't quote substitutions in a message. * - * E.g. + * For example: * ```CodeQL * select foo(), "XSS from '$@'", val, "an unsafe value." // <- bad *