From 323ccc8cea0f996f0d95f4455f385e27303af404 Mon Sep 17 00:00:00 2001
From: Joe Farebrother <joefarebrother@github.com>
Date: Wed, 13 Oct 2021 14:31:23 +0100
Subject: [PATCH 1/4] Add query to find non US spelling

---
 ql/src/queries/style/docs/NonUSSpelling.ql | 38 ++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 ql/src/queries/style/docs/NonUSSpelling.ql

diff --git a/ql/src/queries/style/docs/NonUSSpelling.ql b/ql/src/queries/style/docs/NonUSSpelling.ql
new file mode 100644
index 00000000000..8861629ca87
--- /dev/null
+++ b/ql/src/queries/style/docs/NonUSSpelling.ql
@@ -0,0 +1,38 @@
+/**
+ * @name Non US spelling
+ * @description QLDocs shold use US spelling.
+ * @kind problem
+ * @problem.severity warning
+ * @id ql/non-us-spelling
+ * @tags maintainability
+ * @precision very-high
+ */
+
+import ql
+
+predicate non_us_word(string wrong, string right) {
+  exists(string s |
+    wrong = s.splitAt("/", 0) and
+    right = s.splitAt("/", 1) and
+    s = ["colour/color", "authorise/authorize", "analyse/analyze"]
+  )
+}
+
+bindingset[s]
+predicate contains_non_us_spelling(string s, string wrong, string right) {
+  non_us_word(wrong, right) and
+  (
+    s.matches("%" + wrong + "%") and
+    wrong != "analyse"
+    or
+    // analyses (as a noun) is fine
+    s.regexpMatch(".*analyse[^s].*") and
+    wrong = "analyse"
+  )
+}
+
+from QLDoc doc, string wrong, string right
+where contains_non_us_spelling(doc.getContents().toLowerCase(), wrong, right)
+select doc,
+  "This QLDoc comment contains the non-US spelling '" + wrong + "', which should instead be '" +
+    right + "'."

From fd3c53da9b7f9409d3380f4596fa7085b3e6407d Mon Sep 17 00:00:00 2001
From: Joe Farebrother <joefarebrother@github.com>
Date: Wed, 13 Oct 2021 14:47:41 +0100
Subject: [PATCH 2/4] Add query for class docs that don't start with an
 article.

Returns quite a few results, many of which seem to be TPs.
---
 ql/src/queries/style/docs/ClassDocs.ql | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 ql/src/queries/style/docs/ClassDocs.ql

diff --git a/ql/src/queries/style/docs/ClassDocs.ql b/ql/src/queries/style/docs/ClassDocs.ql
new file mode 100644
index 00000000000..5e335da7109
--- /dev/null
+++ b/ql/src/queries/style/docs/ClassDocs.ql
@@ -0,0 +1,26 @@
+/**
+ * @name Class QLDoc style.
+ * @description The QLDoc for a class should start with "A", "An", or "The".
+ * @kind problem
+ * @problem.severity warning
+ * @id ql/class-doc-style
+ * @tags maintainability
+ * @precision very-high
+ */
+
+import ql
+
+bindingset[s]
+predicate badStyle(string s) {
+  not s.replaceAll("/**", "")
+      .replaceAll("*", "")
+      .splitAt("\n")
+      .trim()
+      .matches(["A %", "An %", "The %"])
+}
+
+from Class c
+where
+  badStyle(c.getQLDoc().getContents()) and
+  not c.isPrivate()
+select c.getQLDoc(), "The QLDoc for a class should start with 'A', 'An', or 'The'."

From 0f71066aaa24ef6922c431259c559e060028398a Mon Sep 17 00:00:00 2001
From: Joe Farebrother <joefarebrother@github.com>
Date: Thu, 14 Oct 2021 11:15:41 +0100
Subject: [PATCH 3/4] Allow comments preceded by INTERNAL

---
 ql/src/queries/style/docs/ClassDocs.ql | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ql/src/queries/style/docs/ClassDocs.ql b/ql/src/queries/style/docs/ClassDocs.ql
index 5e335da7109..6bd67383712 100644
--- a/ql/src/queries/style/docs/ClassDocs.ql
+++ b/ql/src/queries/style/docs/ClassDocs.ql
@@ -16,7 +16,7 @@ predicate badStyle(string s) {
       .replaceAll("*", "")
       .splitAt("\n")
       .trim()
-      .matches(["A %", "An %", "The %"])
+      .matches(["A %", "An %", "The %", "INTERNAL"])
 }
 
 from Class c

From b4a05804fad25da81838e147b28913ed3a1a20c2 Mon Sep 17 00:00:00 2001
From: Joe Farebrother <joefarebrother@github.com>
Date: Thu, 14 Oct 2021 11:35:25 +0100
Subject: [PATCH 4/4] Also allow deprecated headers

---
 ql/src/queries/style/docs/ClassDocs.ql | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ql/src/queries/style/docs/ClassDocs.ql b/ql/src/queries/style/docs/ClassDocs.ql
index 6bd67383712..1dad0867996 100644
--- a/ql/src/queries/style/docs/ClassDocs.ql
+++ b/ql/src/queries/style/docs/ClassDocs.ql
@@ -16,7 +16,7 @@ predicate badStyle(string s) {
       .replaceAll("*", "")
       .splitAt("\n")
       .trim()
-      .matches(["A %", "An %", "The %", "INTERNAL"])
+      .matches(["A %", "An %", "The %", "INTERNAL%", "DEPRECATED%"])
 }
 
 from Class c