Java: Add release note and address review comments.

Author: michaelnebel

docs/codeql/codeql-language-guides/customizing-library-models-for-java.rst

@@ -397,8 +397,8 @@ The following components are supported:
 - **SyntheticGlobal[**\ `name`\ **]** selects the synthetic global with name `name`.
 - **ArrayElement** selects the elements of an array.
 - **Element** selects the elements of a collection-like container.
-- **WithoutElement** selects a collection-like container without its elements (input only).
-- **WithElement** selects the elements of a collection-like container but not the container itself (input only).
+- **WithoutElement** selects a collection-like container without its elements. This is for input only.
+- **WithElement** selects the elements of a collection-like container, but points to the container itself. This is for input only.
 - **MapKey** selects the element keys of a map.
 - **MapValue** selects the element values of a map.
 

java/ql/lib/change-notes/2023-08-04-mad-withoutelement.md

@@ -0,0 +1,4 @@
+---
+category: minorAnalysis
+---
+* Add support for `WithElement` and `WithoutElement` for MaD access paths.

java/ql/lib/ext/java.util.model.yml

@@ -141,6 +141,7 @@ extensions:
       - ["java.util", "LinkedList", False, "LinkedList", "(Collection)", "", "Argument[0].Element", "Argument[this].Element", "value", "manual"]
       - ["java.util", "List", True, "add", "(int,Object)", "", "Argument[1]", "Argument[this].Element", "value", "manual"]
       - ["java.util", "List", True, "addAll", "(int,Collection)", "", "Argument[1].WithElement", "Argument[this]", "value", "manual"]
+      - ["java.util", "List", True, "clear", "()", "", "Argument[this].WithoutElement", "Argument[this]", "value", "manual"]
       - ["java.util", "List", False, "copyOf", "(Collection)", "", "Argument[0].Element", "ReturnValue.Element", "value", "manual"]
       - ["java.util", "List", True, "get", "(int)", "", "Argument[this].Element", "ReturnValue", "value", "manual"]
       - ["java.util", "List", True, "listIterator", "", "", "Argument[this].Element", "ReturnValue.Element", "value", "manual"]
@@ -159,7 +160,6 @@ extensions:
       - ["java.util", "List", True, "set", "(int,Object)", "", "Argument[this].Element", "ReturnValue", "value", "manual"]
       - ["java.util", "List", True, "set", "(int,Object)", "", "Argument[1]", "Argument[this].Element", "value", "manual"]
       - ["java.util", "List", True, "subList", "", "", "Argument[this].Element", "ReturnValue.Element", "value", "manual"]
-      - ["java.util", "List", True, "clear", "()", "", "Argument[this].WithoutElement", "Argument[this]", "value", "manual"]
       - ["java.util", "ListIterator", True, "add", "(Object)", "", "Argument[0]", "Argument[this].Element", "value", "manual"]
       - ["java.util", "ListIterator", True, "previous", "", "", "Argument[this].Element", "ReturnValue", "value", "manual"]
       - ["java.util", "ListIterator", True, "set", "(Object)", "", "Argument[0]", "Argument[this].Element", "value", "manual"]

java/ql/lib/semmle/code/java/dataflow/ExternalFlow.qll

@@ -48,7 +48,8 @@
  *    - "Element": Selects the collection elements of the selected element.
  *    - "WithoutElement": Selects the selected element but without
  *       its collection elements.
- *    - "WithElement": Selects the collection elements of the selected element.
+ *    - "WithElement": Selects the collection elements of the selected element, but
+ *       points to the selected element.
  *
  *    An `output` can be can be a dot separated path consisting of either "",
  *    "Argument[n]", "Argument[n1..n2]", "Parameter", "Parameter[n]",