Merge pull request #816 from geoffw0/code-tidy-27

CPP: Code tidy / qldoc

Author: jbj

cpp/ql/src/semmle/code/cpp/Field.qll

@@ -96,6 +96,7 @@ class BitField extends Field {
    */
   int getBitOffset() { fieldoffsets(underlyingElement(this),_,result) }
 
+  /** Holds if this bitfield is anonymous. */
   predicate isAnonymous() {
     hasName("(unnamed bitfield)")
   }

cpp/ql/src/semmle/code/cpp/Namespace.qll

@@ -36,7 +36,7 @@ class Namespace extends NameQualifyingElement, @namespace {
   /** Holds if this element is named `name`. */
   predicate hasName(string name) { name = this.getName() }
 
-  /** Holds if the namespace is anonymous. */
+  /** Holds if this namespace is anonymous. */
   predicate isAnonymous() {
     hasName("(unnamed namespace)")
   }

cpp/ql/src/semmle/code/cpp/Struct.qll

@@ -30,13 +30,13 @@ class NestedStruct extends Struct {
     this.isMember()
   }
 
-  /** Whether this member is private. */
+  /** Holds if this member is private. */
   predicate isPrivate() { this.hasSpecifier("private") }
 
-  /** Whether this member is protected. */
+  /** Holds if this member is protected. */
   predicate isProtected() { this.hasSpecifier("protected") }
 
-  /** Whether this member is public. */
+  /** Holds if this member is public. */
   predicate isPublic() { this.hasSpecifier("public") }
 
 }

cpp/ql/src/semmle/code/cpp/Type.qll

@@ -1201,11 +1201,11 @@ class AutoType extends TemplateParameter
 // Internal implementation predicates
 //
 
-predicate allSpecifiers(int i, string s) {
+private predicate allSpecifiers(int i, string s) {
   s = rank[i](string t | specifiers(_, t) | t)
 }
 
-predicate internalSpecString(Type t, string res, int i) {
+private predicate internalSpecString(Type t, string res, int i) {
      (if allSpecifiers(i, t.getASpecifier().getName())
       then exists(string spec, string rest
                 | allSpecifiers(i, spec) and res = spec + " " + rest

cpp/ql/src/semmle/code/cpp/Union.qll

@@ -31,13 +31,13 @@ class NestedUnion extends Union {
     this.isMember()
   }
 
-  /** Whether this member is private. */
+  /** Holds if this member is private. */
   predicate isPrivate() { this.hasSpecifier("private") }
 
-  /** Whether this member is protected. */
+  /** Holds if this member is protected. */
   predicate isProtected() { this.hasSpecifier("protected") }
 
-  /** Whether this member is public. */
+  /** Holds if this member is public. */
   predicate isPublic() { this.hasSpecifier("public") }
 
 }

cpp/ql/src/semmle/code/cpp/UserType.qll

@@ -9,17 +9,24 @@ private import semmle.code.cpp.internal.ResolveClass
  * `Enum`, and `TypedefType`.
  */
 class UserType extends Type, Declaration, NameQualifyingElement, AccessHolder, @usertype {
-  /** the name of this type */
+  /** 
+   * Gets the name of this type.
+   */
   override string getName() { usertypes(underlyingElement(this),result,_) }
 
-  /** the simple name of this type, without any template parameters */
+  /**
+   * Gets the simple name of this type, without any template parameters.  For example
+   * if the name of the type is `"myType<int>"`, the simple name is just `"myType"`.
+   */
   string getSimpleName() {
     result = getName().regexpReplaceAll("<.*", "")
   }
 
   override predicate hasName(string name) {
     usertypes(underlyingElement(this),name,_)
   }
+
+  /** Holds if this type is anonymous. */
   predicate isAnonymous() {
     getName().matches("(unnamed%")
   }
@@ -54,20 +61,24 @@ class UserType extends Type, Declaration, NameQualifyingElement, AccessHolder, @
     result.isDefinition()
   }
 
-  /** the location of the definition */
   override Location getDefinitionLocation() {
     if exists(getDefinition()) then
       result = getDefinition().getLocation()
     else
       exists(Class t | this.(Class).isConstructedFrom(t) and result = t.getDefinition().getLocation())
   }
 
-  /** Gets the function that directly encloses this type (if any). */
+  /**
+   * Gets the function that directly encloses this type (if any).
+   */
   Function getEnclosingFunction() {
     enclosingfunction(underlyingElement(this),unresolveElement(result))
   }
 
-  /** Whether this is a local type (i.e. a type that has a directly-enclosing function). */
+  /**
+   * Holds if this is a local type (that is, a type that has a directly-enclosing
+   * function).
+   */
   predicate isLocal() {
     exists(getEnclosingFunction())
   }

cpp/ql/src/semmle/code/cpp/Variable.qll

@@ -264,7 +264,8 @@ class ParameterDeclarationEntry extends VariableDeclarationEntry {
 
 /**
  * A C/C++ variable with block scope [N4140 3.3.3]. In other words, a local
- * variable or a function parameter.
+ * variable or a function parameter. Local variables can be static; use the
+ * `isStatic` member predicate to detect those.
  */
 class LocalScopeVariable extends Variable, @localscopevariable {
   /** Gets the function to which this variable belongs. */
@@ -397,6 +398,10 @@ class FunctionPointerMemberVariable extends MemberVariable {
  */
 class TemplateVariable extends Variable {
   TemplateVariable() { is_variable_template(underlyingElement(this)) }
+
+  /**
+   * Gets an instantiation of this variable template.
+   */
   Variable getAnInstantiation() { result.isConstructedFrom(this) }
 }
 

cpp/ql/src/semmle/code/cpp/XML.qll

@@ -79,7 +79,10 @@ class XMLParent extends @xmlparent {
                          result = this.charsSetUpTo(n-1) + " " + chars))
   }
 
-  /** Append all the character sequences of this XML parent from left to right, separated by a space. */
+  /**
+   * Gets the result of appending all the character sequences of this XML parent from
+   * left to right, separated by a space.
+   */
   string allCharactersString() {
     result = concat(string chars, int pos | xmlChars(_, chars, this, pos, _, _) | chars, " " order by pos)
   }