From 61324f0bb0456d49f73df880e644f1cf8be8a7d2 Mon Sep 17 00:00:00 2001
From: yh-semmle <yh@semmle.com>
Date: Thu, 24 Jan 2019 20:23:10 -0500
Subject: [PATCH] Java 12: enhanced QLDoc for preview features

---
 java/ql/src/semmle/code/java/Expr.qll      |  6 +++-
 java/ql/src/semmle/code/java/Statement.qll | 42 ++++++++++++++++++----
 2 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/java/ql/src/semmle/code/java/Expr.qll b/java/ql/src/semmle/code/java/Expr.qll
index c70cfb3943e..963273f0417 100755
--- a/java/ql/src/semmle/code/java/Expr.qll
+++ b/java/ql/src/semmle/code/java/Expr.qll
@@ -1093,7 +1093,11 @@ class ConditionalExpr extends Expr, @conditionalexpr {
   override string toString() { result = "...?...:..." }
 }
 
-/** A `switch` expression. */
+/**
+ * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+ *
+ * A `switch` expression.
+ */
 deprecated class SwitchExpr extends Expr, @switchexpr {
   /** Gets an immediate child statement of this `switch` expression. */
   Stmt getAStmt() { result.getParent() = this }
diff --git a/java/ql/src/semmle/code/java/Statement.qll b/java/ql/src/semmle/code/java/Statement.qll
index d78edf214a3..43c4b4bf1a8 100755
--- a/java/ql/src/semmle/code/java/Statement.qll
+++ b/java/ql/src/semmle/code/java/Statement.qll
@@ -408,10 +408,18 @@ class SwitchCase extends Stmt, @case {
   /** Gets the switch statement to which this case belongs, if any. */
   SwitchStmt getSwitch() { result.getACase() = this }
 
-  /** Gets the switch expression to which this case belongs, if any. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Gets the switch expression to which this case belongs, if any.
+   */
   deprecated SwitchExpr getSwitchExpr() { result.getACase() = this }
 
-  /** Holds if this `case` is a switch labeled rule of the form `... -> ...`. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Holds if this `case` is a switch labeled rule of the form `... -> ...`.
+   */
   deprecated predicate isRule() {
     exists(Expr e | e.getParent() = this | e.getIndex() = -1)
     or
@@ -426,13 +434,25 @@ class ConstCase extends SwitchCase {
   /** Gets the `case` constant at index 0. */
   Expr getValue() { result.getParent() = this and result.getIndex() = 0 }
 
-  /** Gets the `case` constant at the specified index. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Gets the `case` constant at the specified index.
+   */
   deprecated Expr getValue(int i) { result.getParent() = this and result.getIndex() = i and i >= 0 }
 
-  /** Gets the expression on the right-hand side of the arrow, if any. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Gets the expression on the right-hand side of the arrow, if any.
+   */
   deprecated Expr getRuleExpression() { result.getParent() = this and result.getIndex() = -1 }
 
-  /** Gets the statement on the right-hand side of the arrow, if any. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Gets the statement on the right-hand side of the arrow, if any.
+   */
   deprecated Stmt getRuleStatement() { result.getParent() = this and result.getIndex() = -1 }
 
   /** Gets a printable representation of this statement. May include more detail than `toString()`. */
@@ -572,10 +592,18 @@ class BreakStmt extends Stmt, @breakstmt {
   /** Holds if this `break` statement has an explicit label. */
   predicate hasLabel() { exists(string s | s = this.getLabel()) }
 
-  /** Gets the value of this `break` statement, if any. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Gets the value of this `break` statement, if any.
+   */
   deprecated Expr getValue() { result.getParent() = this }
 
-  /** Holds if this `break` statement has a value. */
+  /**
+   * DEPRECATED: Preview feature in Java 12. Subject to removal in a future release.
+   *
+   * Holds if this `break` statement has a value.
+   */
   deprecated predicate hasValue() { exists(Expr e | e.getParent() = this) }
 
   /** Gets a printable representation of this statement. May include more detail than `toString()`. */