Fix syntax errors in QL comments

cklin · cklin · commit d6f0bbb81669 · 2022-04-28T11:53:36.000-07:00
diff --git a/cpp/ql/lib/semmle/code/cpp/Function.qll b/cpp/ql/lib/semmle/code/cpp/Function.qll
@@ -38,8 +38,8 @@ class Function extends Declaration, ControlFlowNode, AccessHolder, @function {
    * int z = min(5, 7);
    * ```
    * The full signature of the function called on the last line would be
-   * "min<int>(int, int) -> int", and the full signature of the uninstantiated
-   * template on the first line would be "min<T>(T, T) -> T".
+   * `min<int>(int, int) -> int`, and the full signature of the uninstantiated
+   * template on the first line would be `min<T>(T, T) -> T`.
    */
   string getFullSignature() {
     exists(string name, string templateArgs, string args |
diff --git a/cpp/ql/src/Likely Bugs/Memory Management/SuspiciousCallToMemset.ql b/cpp/ql/src/Likely Bugs/Memory Management/SuspiciousCallToMemset.ql
@@ -2,7 +2,7 @@
  * @name Suspicious call to memset
  * @description Use of memset where the size argument is computed as the size of
  *              some non-struct type. When initializing a buffer, you should specify
- *              its size as <number of elements> * <size of one element> to ensure
+ *              its size as `<number of elements> * <size of one element>` to ensure
  *              portability.
  * @kind problem
  * @id cpp/suspicious-call-to-memset
diff --git a/csharp/ql/lib/semmle/code/csharp/exprs/Call.qll b/csharp/ql/lib/semmle/code/csharp/exprs/Call.qll
@@ -175,8 +175,8 @@ class Call extends DotNet::Call, Expr, @call {
    * - Line 10: The static target is `Type.InvokeMember()`, whereas the run-time targets
    *   are both `A.M()` and `B.M()`.
    *
-   * - Line 16: There is no static target (delegate call) but the delegate `i => { }` (line
-   *   20) is a run-time target.
+   * - Line 16: There is no static target (delegate call) but the delegate `i => { }`
+   *   (line 20) is a run-time target.
    */
   override Callable getARuntimeTarget() {
     exists(DispatchCall dc | dc.getCall() = this | result = dc.getADynamicTarget())
diff --git a/csharp/ql/src/API Abuse/IncorrectCompareToSignature.ql b/csharp/ql/src/API Abuse/IncorrectCompareToSignature.ql
@@ -1,6 +1,6 @@
 /**
  * @name Potentially incorrect CompareTo(...) signature
- * @description The declaring type of a method with signature 'CompareTo(T)' does not implement 'IComparable<T>'.
+ * @description The declaring type of a method with signature `CompareTo(T)` does not implement `IComparable<T>`.
  * @kind problem
  * @problem.severity warning
  * @precision medium
diff --git a/csharp/ql/src/Documentation/XmldocExtraParam.ql b/csharp/ql/src/Documentation/XmldocExtraParam.ql
@@ -1,6 +1,6 @@
 /**
  * @name Incorrect parameter name in documentation
- * @description The parameter name given in a '<param>' tag does not exist. Rename the parameter or
+ * @description The parameter name given in a `<param>` tag does not exist. Rename the parameter or
  *              change the name in the documentation to ensure that they are the same.
  * @kind problem
  * @problem.severity recommendation
diff --git a/csharp/ql/src/Documentation/XmldocExtraTypeParam.ql b/csharp/ql/src/Documentation/XmldocExtraTypeParam.ql
@@ -1,6 +1,6 @@
 /**
  * @name Incorrect type parameter name in documentation
- * @description The type parameter name given in a '<typeparam>' tag does not exist. Rename the parameter or
+ * @description The type parameter name given in a `<typeparam>` tag does not exist. Rename the parameter or
  *              change the name in the documentation to ensure that they are the same.
  * @kind problem
  * @problem.severity recommendation
diff --git a/csharp/ql/src/Documentation/XmldocMissingException.ql b/csharp/ql/src/Documentation/XmldocMissingException.ql
@@ -1,6 +1,6 @@
 /**
  * @name Missing documentation for exception
- * @description Exceptions thrown by the method should be documented using '<exception cref="..."> </exception>' tags.
+ * @description Exceptions thrown by the method should be documented using `<exception cref="..."> </exception>` tags.
  *              Ensure that the correct type of the exception is given in the 'cref' attribute.
  * @kind problem
  * @problem.severity recommendation
diff --git a/csharp/ql/src/Documentation/XmldocMissingParam.ql b/csharp/ql/src/Documentation/XmldocMissingParam.ql
@@ -1,6 +1,6 @@
 /**
  * @name Missing documentation for parameter
- * @description All parameters should be documented using '<param name="..."> </param>' tags.
+ * @description All parameters should be documented using `<param name="..."> </param>` tags.
  *              Ensure that the name attribute matches the name of the parameter.
  * @kind problem
  * @problem.severity recommendation
diff --git a/csharp/ql/src/Documentation/XmldocMissingReturn.ql b/csharp/ql/src/Documentation/XmldocMissingReturn.ql
@@ -1,7 +1,7 @@
 /**
  * @name Missing documentation for return value
  * @description The method returns a value, but the return value is not documented using
- *              a '<returns>' tag.
+ *              a `<returns>` tag.
  * @kind problem
  * @problem.severity recommendation
  * @precision low
diff --git a/csharp/ql/src/Documentation/XmldocMissingSummary.ql b/csharp/ql/src/Documentation/XmldocMissingSummary.ql
@@ -1,6 +1,6 @@
 /**
  * @name Missing a summary in documentation comment
- * @description The documentation comment does not contain a '<summary>' tag.
+ * @description The documentation comment does not contain a `<summary>` tag.
  * @kind problem
  * @problem.severity recommendation
  * @precision high
diff --git a/csharp/ql/src/Documentation/XmldocMissingTypeParam.ql b/csharp/ql/src/Documentation/XmldocMissingTypeParam.ql
@@ -1,6 +1,6 @@
 /**
  * @name Missing documentation for type parameter
- * @description All type parameters should be documented using '<typeparam name="..."> </typeparam>' tags.
+ * @description All type parameters should be documented using `<typeparam name="..."> </typeparam>` tags.
  *              Ensure that the 'name' attribute matches the name of the type parameter.
  * @kind problem
  * @problem.severity recommendation
diff --git a/java/ql/lib/semmle/code/java/frameworks/JaxWS.qll b/java/ql/lib/semmle/code/java/frameworks/JaxWS.qll
@@ -390,7 +390,7 @@ private class HttpHeadersModel extends SummaryModelCsv {
 }
 
 /**
- * Model MultivaluedMap, which extends Map<K, List<V>> and provides a few extra helper methods.
+ * Model MultivaluedMap, which extends `Map<K, List<V>>` and provides a few extra helper methods.
  */
 private class MultivaluedMapModel extends SummaryModelCsv {
   override predicate row(string row) {
diff --git a/java/ql/lib/semmle/code/java/frameworks/spring/SpringEntry.qll b/java/ql/lib/semmle/code/java/frameworks/spring/SpringEntry.qll
@@ -64,7 +64,7 @@ class SpringEntry extends SpringXmlElement {
 
   /**
    * Gets the bean pointed to by either the `value-ref` attribute, or a nested
-   * `<ref> or `<idref>` element, whichever is present.
+   * `<ref>` or `<idref>` element, whichever is present.
    */
   SpringBean getValueRefBean() {
     if this.hasValueRefString()
diff --git a/java/ql/src/experimental/Security/CWE/CWE-939/IncorrectURLVerification.ql b/java/ql/src/experimental/Security/CWE/CWE-939/IncorrectURLVerification.ql
@@ -15,7 +15,7 @@ import java
 
 /**
  * The Java class `android.R.string` specific to Android applications, which contains references to application specific resources defined in /res/values/strings.xml.
- * For example, <resources>...<string name="host">example.com</string>...</resources> in the application com.example.android.web can be referred as R.string.host with the type com.example.android.web.R$string
+ * For example, `<resources>...<string name="host">example.com</string>...</resources>` in the application com.example.android.web can be referred as R.string.host with the type com.example.android.web.R$string
  */
 class AndroidRString extends RefType {
   AndroidRString() { this.hasQualifiedName(_, "R$string") }
diff --git a/javascript/ql/lib/semmle/javascript/DefUse.qll b/javascript/ql/lib/semmle/javascript/DefUse.qll
@@ -8,7 +8,7 @@ import javascript
  * This predicate covers four kinds of definitions:
  *
  * <table border="1">
- * <tr><th>Example<th><code>def</code><th><code>lhs</code><th><code>rhs</code></tr>
+ * <tr><th>Example</th><th><code>def</code></th><th><code>lhs</code></th><th><code>rhs</code></th></tr>
  * <tr><td><code>x = y</code><td><code>x = y</code><td><code>x</code><td><code>y</code></tr>
  * <tr><td><code>var a = b</code><td><code>var a = b</code><td><code>a</code><td><code>b</code></tr>
  * <tr><td><code>function f { ... }</code><td><code>f</code><td><code>f</code><td><code>function f { ... }</code></tr>
@@ -56,7 +56,7 @@ private predicate defn(ControlFlowNode def, Expr lhs, AST::ValueNode rhs) {
  * where there is no explicit right hand side:
  *
  * <table border="1">
- * <tr><th>Example<th><code>def</code><th><code>lhs</code></tr>
+ * <tr><th>Example</th><th><code>def</code></th><th><code>lhs</code></th></tr>
  * <tr><td><code>x += y</code><td><code>x += y</code><td><code>x</code></tr>
  * <tr><td><code>++z.q</code><td><code>++z.q</code><td><code>z.q</code></tr>
  * <tr><td><code>import { a as b } from 'm'</code><td><code>a as b</code><td><code>b</code></tr>
diff --git a/javascript/ql/lib/semmle/javascript/Externs.qll b/javascript/ql/lib/semmle/javascript/Externs.qll
@@ -53,7 +53,7 @@ import javascript
  *
  * /**
  *  * @param {!Object} obj
- *  * @return {!Array<string>}
+ *  * @return {!Array&lt;string&gt;}
  *  *&#47;
  * Object.keys = function(obj) {};
  *
@@ -109,7 +109,7 @@ class ExternalTypedef extends ExternalDecl, VariableDeclarator {
  *
  * /**
  *  * @param {!Object} obj
- *  * @return {!Array<string>}
+ *  * @return {!Array&lt;string&gt;}
  *  *&#47;
  * Object.keys = function(obj) {};
  *
@@ -214,7 +214,7 @@ class ExternalGlobalVarDecl extends ExternalGlobalDecl, VariableDeclarator {
  * <pre>
  * /**
  *  * @param {!Object} obj
- *  * @return {!Array<string>}
+ *  * @return {!Array&lt;string&gt;}
  *  *&#47;
  * Object.keys = function(obj) {};
  *
@@ -273,7 +273,7 @@ class ExternalMemberDecl extends ExternalVarDecl, ExprStmt {
  * <pre>
  * /**
  *  * @param {!Object} obj
- *  * @return {!Array<string>}
+ *  * @return {!Array&lt;string&gt;}
  *  *&#47;
  * Object.keys = function(obj) {};
  *
diff --git a/javascript/ql/lib/semmle/javascript/security/dataflow/UnsafeShellCommandConstructionCustomizations.qll b/javascript/ql/lib/semmle/javascript/security/dataflow/UnsafeShellCommandConstructionCustomizations.qll
@@ -273,7 +273,7 @@ module UnsafeShellCommandConstruction {
   }
 
   /**
-   * A guard of the form `typeof x === "<T>"`, where <T> is  "number", or "boolean",
+   * A guard of the form `typeof x === "<T>"`, where `<T>` is  "number", or "boolean",
    * which sanitizes `x` in its "then" branch.
    */
   class TypeOfSanitizer extends TaintTracking::SanitizerGuardNode, DataFlow::ValueNode {
