Merge pull request github#3776 from geoffw0/qldoc

C++: QLDoc ObjectiveC.qll, BufferWrite.qll, FileWrite.qll, OutputWrite.qll

Author: MathiasVP

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

@@ -1,3 +1,7 @@
+/**
+ * DEPRECATED: Objective-C is no longer supported.
+ */
+
 import semmle.code.cpp.Class
 private import semmle.code.cpp.internal.ResolveClass
 

cpp/ql/src/semmle/code/cpp/security/BufferWrite.qll

@@ -146,6 +146,9 @@ class StrCopyBW extends BufferWriteCall {
     )
   }
 
+  /**
+   * Gets the index of the parameter that is the maximum size of the copy (in characters).
+   */
   int getParamSize() {
     exists(TopLevelFunction fn, string name |
       fn = getTarget() and
@@ -161,6 +164,9 @@ class StrCopyBW extends BufferWriteCall {
     )
   }
 
+  /**
+   * Gets the index of the parameter that is the source of the copy.
+   */
   int getParamSrc() {
     exists(TopLevelFunction fn, string name |
       fn = getTarget() and
@@ -194,8 +200,14 @@ class StrCopyBW extends BufferWriteCall {
 class StrCatBW extends BufferWriteCall {
   StrCatBW() { exists(TopLevelFunction fn | fn = getTarget() and fn instanceof StrcatFunction) }
 
+  /**
+   * Gets the index of the parameter that is the maximum size of the copy (in characters).
+   */
   int getParamSize() { if exists(getArgument(2)) then result = 2 else none() }
 
+  /**
+   * Gets the index of the parameter that is the source of the copy.
+   */
   int getParamSrc() { result = 1 }
 
   override Type getBufferType() {
@@ -349,6 +361,9 @@ class SnprintfBW extends BufferWriteCall {
     )
   }
 
+  /**
+   * Gets the index of the parameter that is the size of the destination (in characters).
+   */
   int getParamSize() { result = 1 }
 
   override Type getBufferType() {
@@ -399,6 +414,9 @@ class GetsBW extends BufferWriteCall {
     )
   }
 
+  /**
+   * Gets the index of the parameter that is the maximum number of characters to be read.
+   */
   int getParamSize() { if exists(getArgument(1)) then result = 1 else none() }
 
   override Type getBufferType() { result = this.getTarget().getParameter(0).getUnspecifiedType() }
@@ -434,6 +452,9 @@ class ScanfBW extends BufferWrite {
     )
   }
 
+  /**
+   * Gets the index of the parameter that is the first format argument.
+   */
   int getParamArgs() {
     exists(FunctionCall fc |
       this = fc.getArgument(_) and

cpp/ql/src/semmle/code/cpp/security/FileWrite.qll

@@ -1,13 +1,23 @@
+/**
+ * Provides classes for modelling writing of data to files through various standard mechanisms such as `fprintf`, `fwrite` and `operator<<`.
+ */
+
 import cpp
 
 /**
- * A function call that writes to a file
+ * A function call that writes to a file.
  */
 class FileWrite extends Expr {
   FileWrite() { fileWrite(this, _, _) }
 
+  /**
+   * Gets a source expression of this write.
+   */
   Expr getASource() { fileWrite(this, result, _) }
 
+  /**
+   * Gets the expression for the object being written to.
+   */
   Expr getDest() { fileWrite(this, _, result) }
 }
 
@@ -44,17 +54,17 @@ class BasicOStreamCall extends FunctionCall {
  */
 abstract class ChainedOutputCall extends BasicOStreamCall {
   /**
-   * The source expression of this output.
+   * Gets the source expression of this output.
    */
   abstract Expr getSource();
 
   /**
-   * The immediate destination expression of this output.
+   * Gets the immediate destination expression of this output.
    */
   abstract Expr getDest();
 
   /**
-   * The destination at the far left-hand end of the output chain.
+   * Gets the destination at the far left-hand end of the output chain.
    */
   Expr getEndDest() {
     // recurse into the destination
@@ -108,7 +118,7 @@ class WriteFunctionCall extends ChainedOutputCall {
 }
 
 /**
- * Whether the function call is a call to &lt;&lt; that eventually starts at the given file stream.
+ * Whether the function call is a call to `operator<<` or a similar function, that eventually starts at the given file stream.
  */
 private predicate fileStreamChain(ChainedOutputCall out, Expr source, Expr dest) {
   source = out.getSource() and

cpp/ql/src/semmle/code/cpp/security/OutputWrite.qll

@@ -1,12 +1,19 @@
+/**
+ * Provides classes for modelling output to standard output / standard error through various mechanisms such as `printf`, `puts` and `operator<<`.
+ */
+
 import cpp
 import FileWrite
 
 /**
- *  A function call that writes to standard output or standard error
+ * A function call that writes to standard output or standard error.
  */
 class OutputWrite extends Expr {
   OutputWrite() { outputWrite(this, _) }
 
+  /**
+   * Gets a source expression for this output.
+   */
   Expr getASource() { outputWrite(this, result) }
 }
 
@@ -49,7 +56,7 @@ private predicate outputFile(Expr e) {
 }
 
 /**
- * is the function call a write to standard output or standard error from 'source'
+ * Holds if the function call is a write to standard output or standard error from 'source'.
  */
 private predicate outputWrite(Expr write, Expr source) {
   exists(Function f, int arg |