C++: QLDoc FileWrite and OutputWrite.

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 |