C++: respond to doc comments

Author: Robert Marsh

change-notes/1.19/analysis-cpp.md

@@ -6,10 +6,10 @@
 
 | **Query**                   | **Tags**  | **Purpose**                                                        |
 |-----------------------------|-----------|--------------------------------------------------------------------|
-| Cast between HRESULT and a Boolean type (`cpp/hresult-boolean-conversion`) | external/cwe/cwe-253 | Finds logic errors caused by mistakenly treating the Windows `HRESULT` type as a Boolean instead of testing it with the appropriate macros. Enabled by default. |
+| Cast between `HRESULT` and a Boolean type (`cpp/hresult-boolean-conversion`) | external/cwe/cwe-253 | Finds logic errors caused by mistakenly treating the Windows `HRESULT` type as a Boolean instead of testing it with the appropriate macros. Enabled by default. |
 | Setting a DACL to `NULL` in a `SECURITY_DESCRIPTOR` (`cpp/unsafe-dacl-security-descriptor`) | external/cwe/cwe-732 | This query finds code that creates world-writable objects on Windows by setting their DACL to `NULL`. Enabled by default. |
-| Cast from char* to wchar_t* | security, external/cwe/cwe-704 | Detects potentially dangerous casts from char* to wchar_t*.  Enabled by default on LGTM. |
-| Dead code due to goto or break statement (`cpp/dead-code-goto`) | maintainability, external/cwe/cwe-561 | Detects dead code following a goto or break statement. Enabled by default on LGTM. |
+| Cast from `char*` to `wchar_t*` | security, external/cwe/cwe-704 | Detects potentially dangerous casts from `char*` to `wchar_t*`.  Enabled by default on LGTM. |
+| Dead code due to `goto` or `break` statement (`cpp/dead-code-goto`) | maintainability, external/cwe/cwe-561 | Detects dead code following a goto or break statement. Enabled by default on LGTM. |
 
 ## Changes to existing queries
 

cpp/ql/src/Critical/DeadCodeGoto.qhelp

@@ -6,23 +6,23 @@
 
 <overview>
 <p>
-Code following a goto or break statement will not be executed, unless there is a label or switch
-case. When the code is necessary, this leads to logical errors or resource leaks. If the code is
-unnecessary, it may confuse readers.
+Code immediately following a <code>goto</code> or <code>break</code> statement will not be executed,
+unless there is a label or switch case. When the code is necessary, this leads to logical errors or
+resource leaks. If the code is unnecessary, it may confuse readers.
 </p>
 </overview>
 <recommendation>
 <p>
-If the unreachable code is necessary, move the goto or break statement to after the code.
-Otherwise, delete the unreachable code.
+If the unreachable code is necessary, move the <code>goto</code> or <code>break</code> statement to
+after the code. Otherwise, delete the unreachable code.
 </p>
 
 </recommendation>
 <example><sample src="DeadCodeGoto.cpp" />
 </example>
 <references>
 <li>
-  The CERT C Secure Coding Standard: <a href="https://wiki.sei.cmu.edu/confluence/display/c/MSC12-C.+Detect+and+remove+code+that+has+no+effect+or+is+never+executed">MSC12-C. Detect and remove code that has no effect or is never executed</a>
+  The CERT C Secure Coding Standard: <a href="https://wiki.sei.cmu.edu/confluence/display/c/MSC12-C.+Detect+and+remove+code+that+has+no+effect+or+is+never+executed">MSC12-C. Detect and remove code that has no effect or is never executed</a>.
 </li>
 </references>
 </qhelp>

cpp/ql/src/Critical/DeadCodeGoto.ql

@@ -29,4 +29,4 @@ where b.getStmt(i) = js
   and not s.(BreakStmt).getBreakable() instanceof SwitchStmt
   // the jump isn't a goto into the body of the next statement
   and not exists (LabelStmt ls | s.(Loop).getStmt().getAChild*() = ls | ls.getName() = js.(GotoStmt).getName())
-select js, "This statement makes $@ dead.", s, s.toString()
+select js, "This statement makes $@ unreachable.", s, s.toString()

cpp/ql/test/query-tests/Critical/DeadCodeGoto/DeadCodeGoto.expected

@@ -1,3 +1,3 @@
-| test.cpp:2:2:2:12 | goto ... | This statement makes $@ dead. | test.cpp:3:2:3:5 | ExprStmt | ExprStmt |
-| test.cpp:9:3:9:8 | break; | This statement makes $@ dead. | test.cpp:10:3:10:6 | ExprStmt | ExprStmt |
-| test.cpp:37:3:37:8 | break; | This statement makes $@ dead. | test.cpp:38:3:38:11 | return ... | return ... |
+| test.cpp:2:2:2:12 | goto ... | This statement makes $@ unreachable. | test.cpp:3:2:3:5 | ExprStmt | ExprStmt |
+| test.cpp:9:3:9:8 | break; | This statement makes $@ unreachable. | test.cpp:10:3:10:6 | ExprStmt | ExprStmt |
+| test.cpp:37:3:37:8 | break; | This statement makes $@ unreachable. | test.cpp:38:3:38:11 | return ... | return ... |