Merge pull request #500 from owen-mc/add-missing-qldoc

Add missing QLDoc for public declarations

Author: owen-mc

.github/workflows/docs-review.yml

@@ -0,0 +1,29 @@
+# When a PR is labelled with 'ready-for-docs-review',
+# this workflow comments on the PR to notify the GitHub CodeQL docs team.
+name: Request docs review
+on:
+  # Runs in the context of the base repo.
+  # This gives the workflow write access to comment on PRs.
+  # The workflow should not check out or build the given ref,
+  # or use untrusted data from the event payload in a command line.
+  pull_request_target:
+    types: [labeled]
+
+jobs:
+  request-docs-review:
+    name: Request docs review
+    # Run only on labelled PRs to the main repository.
+    # Do not run on PRs to forks.
+    if:
+      github.event.label.name == 'ready-for-docs-review'
+      && github.event.pull_request.draft == false
+      && github.event.pull_request.base.repo.full_name == 'github/codeql-go'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment to request docs review
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          gh pr comment "$PR_NUMBER" --repo "github/codeql-go" \
+            --body "Hello @github/docs-content-codeql - this PR is ready for docs review."

ql/src/experimental/CWE-327/WeakCryptoAlgorithmCustomizations.qll

@@ -8,6 +8,11 @@ import go
 private import semmle.go.security.SensitiveActions
 private import CryptoLibraries
 
+/**
+ * Provides default sources, sinks and sanitizers for reasoning about
+ * sensitive information in weak cryptographic algorithms,
+ * as well as extension points for adding your own.
+ */
 module WeakCryptoAlgorithm {
   /**
    * A data flow source for sensitive information in weak cryptographic algorithms.

ql/src/semmle/go/Expr.qll

@@ -344,6 +344,7 @@ class RuneLit = CharLit;
 class StringLit extends @stringlit, BasicLit {
   override string getAPrimaryQlClass() { result = "StringLit" }
 
+  /** Holds if this string literal is a raw string literal. */
   predicate isRaw() { this.getText().matches("`%`") }
 }
 

ql/src/semmle/go/frameworks/Beego.qll

@@ -7,6 +7,10 @@ import go
 import semmle.go.security.Xss
 private import semmle.go.security.SafeUrlFlowCustomizations
 
+/**
+ * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * from the [Beego](`github.com/beego/beego`) package.
+ */
 module Beego {
   /** Gets the module path `github.com/astaxie/beego` or `github.com/beego/beego`. */
   bindingset[result]

ql/src/semmle/go/frameworks/BeegoOrm.qll

@@ -6,6 +6,10 @@
 import go
 private import semmle.go.security.StoredXssCustomizations
 
+/**
+ * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * from the [Beego ORM](`github.com/astaxie/beego/orm`) subpackage.
+ */
 module BeegoOrm {
   /** Gets the package name `github.com/astaxie/beego/orm`. */
   bindingset[result]

ql/src/semmle/go/frameworks/EvanphxJsonPatch.qll

@@ -45,12 +45,12 @@ private module EvanphxJsonPatch {
     }
   }
 
-  private class Apply extends TaintTracking::FunctionModel {
+  private class Apply extends TaintTracking::FunctionModel, Method {
     Apply() {
       exists(string fn |
         fn in ["Apply", "ApplyWithOptions", "ApplyIndent", "ApplyIndentWithOptions"]
       |
-        this.hasQualifiedName(packagePath(), fn)
+        this.hasQualifiedName(packagePath(), "Patch", fn)
       )
     }
 

ql/src/semmle/go/frameworks/GoRestfulHttp.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides models of the [go-restful library](https://github.com/emicklei/go-restful).
+ */
+
 import go
 
 /**

ql/src/semmle/go/frameworks/SQL.qll

@@ -217,6 +217,9 @@ module SQL {
   }
 }
 
+/**
+ * Provides classes for working with the [GORM](https://gorm.io/) package.
+ */
 module Gorm {
   /** Gets the package name for Gorm. */
   bindingset[result]

ql/src/semmle/go/frameworks/SystemCommandExecutors.qll

@@ -77,6 +77,10 @@ private class GoShCommandExecution extends SystemCommandExecution::Range, DataFl
   override DataFlow::Node getCommandName() { result = this.getArgument(0) }
 }
 
+/**
+ * Provides classes for working with the
+ * [golang.org/x/crypto/ssh](https://pkg.go.dev/golang.org/x/crypto/ssh) package.
+ */
 module CryptoSsh {
   /** Gets the package path `golang.org/x/crypto/ssh`. */
   bindingset[result]

ql/src/semmle/go/frameworks/WebSocket.qll

@@ -298,24 +298,39 @@ module WebSocketReader {
   }
 }
 
+/**
+ * Provides classes for working with the [Gorilla WebSocket](https://github.com/gorilla/websocket)
+ * package.
+ */
 module GorillaWebsocket {
   /** Gets the package name `github.com/gorilla/websocket`. */
   bindingset[result]
   string packagePath() { result = package("github.com/gorilla", "websocket") }
 }
 
+/**
+ * Provides classes for working with the
+ * [golang.org/x/net/websocket](https://pkg.go.dev/golang.org/x/net/websocket) package.
+ */
 module GolangOrgXNetWebsocket {
   /** Gets the package name `golang.org/x/net/websocket`. */
   bindingset[result]
   string packagePath() { result = package("golang.org/x/net", "websocket") }
 }
 
+/**
+ * Provides classes for working with the [nhooyr.io/websocket](http://nhooyr.io/websocket)
+ * package.
+ */
 module NhooyrWebSocket {
   /** Gets the package name `nhooyr.io/websocket/`. */
   bindingset[result]
   string packagePath() { result = package("nhooyr.io/websocket", "") }
 }
 
+/**
+ * Provides classes for working with the [ws](https://github.com/gobwas/ws) package.
+ */
 module GobwasWs {
   /** Gets the package name `github.com/gobwas/ws`. */
   bindingset[result]