C++: QLDoc Synchronization.qll and improve existing QLDoc.

cpp/ql/src/semmle/code/cpp/commons/Synchronization.qll

@@ -23,8 +23,7 @@ abstract class MutexType extends Type {
   abstract predicate trylockAccess(FunctionCall fc, Expr arg);
 
   /**
-   * Holds if `fc` is a call that unlocks mutex `arg`
-   * of this type.
+   * Holds if `fc` is a call that unlocks mutex `arg` of this type.
    */
   abstract predicate unlockAccess(FunctionCall fc, Expr arg);
 
@@ -38,8 +37,7 @@ abstract class MutexType extends Type {
   }
 
   /**
-   * Holds if `fc` is a call that locks or tries to lock any
-   * mutex of this type.
+   * Gets a call that locks or tries to lock any mutex of this type.
    */
   FunctionCall getLockAccess() {
     result = getMustlockAccess() or
@@ -47,44 +45,44 @@ abstract class MutexType extends Type {
   }
 
   /**
-   * Holds if `fc` is a call that always locks any mutex of this type.
+   * Gets a call that always locks any mutex of this type.
    */
   FunctionCall getMustlockAccess() { this.mustlockAccess(result, _) }
 
   /**
-   * Holds if `fc` is a call that tries to lock any mutex of this type,
+   * Gets a call that tries to lock any mutex of this type,
    * by may return without success.
    */
   FunctionCall getTrylockAccess() { this.trylockAccess(result, _) }
 
   /**
-   * Holds if `fc` is a call that unlocks any mutex of this type.
+   * Gets a call that unlocks any mutex of this type.
    */
   FunctionCall getUnlockAccess() { this.unlockAccess(result, _) }
 
   /**
-   * DEPRECATED: use mustlockAccess(fc, arg) instead
+   * DEPRECATED: use mustlockAccess(fc, arg) instead.
    */
   deprecated Function getMustlockFunction() { result = getMustlockAccess().getTarget() }
 
   /**
-   * DEPRECATED: use trylockAccess(fc, arg) instead
+   * DEPRECATED: use trylockAccess(fc, arg) instead.
    */
   deprecated Function getTrylockFunction() { result = getTrylockAccess().getTarget() }
 
   /**
-   * DEPRECATED: use lockAccess(fc, arg) instead
+   * DEPRECATED: use lockAccess(fc, arg) instead.
    */
   deprecated Function getLockFunction() { result = getLockAccess().getTarget() }
 
   /**
-   * DEPRECATED: use unlockAccess(fc, arg) instead
+   * DEPRECATED: use unlockAccess(fc, arg) instead.
    */
   deprecated Function getUnlockFunction() { result = getUnlockAccess().getTarget() }
 }
 
 /**
- * A function that looks like a lock function.
+ * Gets a function that looks like a lock function.
  */
 private Function mustlockCandidate() {
   exists(string name | name = result.getName() |
@@ -94,7 +92,7 @@ private Function mustlockCandidate() {
 }
 
 /**
- * A function that looks like a try-lock function.
+ * Gets a function that looks like a try-lock function.
  */
 private Function trylockCandidate() {
   exists(string name | name = result.getName() |
@@ -104,7 +102,7 @@ private Function trylockCandidate() {
 }
 
 /**
- * A function that looks like an unlock function.
+ * Gets a function that looks like an unlock function.
  */
 private Function unlockCandidate() {
   exists(string name | name = result.getName() |
@@ -171,7 +169,7 @@ class DefaultMutexType extends MutexType {
   }
 }
 
-/** Get the mutex argument of a call to lock or unlock. */
+/** Holds if `arg` is the mutex argument of a call to lock or unlock. */
 private predicate lockArg(Expr arg, MutexType argType, FunctionCall call) {
   argType = arg.getUnderlyingType().stripType() and
   (
@@ -184,18 +182,31 @@ private predicate lockArg(Expr arg, MutexType argType, FunctionCall call) {
   //       `MutexType.mustlockAccess`.
 }
 
+/**
+ * Holds if `call` is a call that locks or tries to lock its argument `arg`.
+ */
 predicate lockCall(Expr arg, FunctionCall call) {
   exists(MutexType t | lockArg(arg, t, call) and call = t.getLockAccess())
 }
 
+/**
+ * Holds if `call` is a call that always locks its argument `arg`.
+ */
 predicate mustlockCall(Expr arg, FunctionCall call) {
   exists(MutexType t | lockArg(arg, t, call) and call = t.getMustlockAccess())
 }
 
+/**
+ * Holds if `call` is a call that tries to lock its argument `arg`, but may
+ * return without success.
+ */
 predicate trylockCall(Expr arg, FunctionCall call) {
   exists(MutexType t | lockArg(arg, t, call) and call = t.getTrylockAccess())
 }
 
+/**
+ * Holds if `call` is a call that unlocks its argument `arg`.
+ */
 predicate unlockCall(Expr arg, FunctionCall call) {
   exists(MutexType t | lockArg(arg, t, call) and call = t.getUnlockAccess())
 }