Rust: add some QLdoc for optional steps/barriers

Author: aibaars

rust/ql/lib/codeql/rust/dataflow/internal/Content.qll

@@ -214,6 +214,11 @@ final class SingletonContentSet extends ContentSet, TSingletonContentSet {
   override Content getAReadContent() { result = c }
 }
 
+/**
+ * A step in a flow summary defined using `OptionalStep[name]`. An `OptionalStep` is "opt-in", which means
+ * that by default the step is not present in the flow summary and needs to be explicitly enabled by defining
+ * an additional flow step.
+ */
 final class OptionalStep extends ContentSet, TOptionalStep {
   override string toString() {
     exists(string name |
@@ -227,6 +232,10 @@ final class OptionalStep extends ContentSet, TOptionalStep {
   override Content getAReadContent() { none() }
 }
 
+/**
+ * A step in a flow summary defined using `OptionalBarrier[name]`. An `OptionalBarrier` is "opt-out", by default
+ * data can flow freely through the step. Flow through the step can be explicity blocked by defining its node as a barrier.
+ */
 final class OptionalBarrier extends ContentSet, TOptionalBarrier {
   override string toString() {
     exists(string name |

rust/ql/lib/codeql/rust/dataflow/internal/DataFlowImpl.qll

@@ -1133,6 +1133,11 @@ import Cached
 
 cached
 private module OptionalSteps {
+  /**
+   * A step in a flow summary defined using `OptionalStep[name]`. An `OptionalStep` is "opt-in", which means
+   * that by default the step is not present in the flow summary and needs to be explicitly enabled by defining
+   * an additional flow step.
+   */
   cached
   predicate optionalStep(Node node1, string name, Node node2) {
     FlowSummaryImpl::Private::Steps::summaryReadStep(node1.(FlowSummaryNode).getSummaryNode(),
@@ -1141,6 +1146,10 @@ private module OptionalSteps {
       TOptionalStep(name), node2.(FlowSummaryNode).getSummaryNode())
   }
 
+  /**
+   * A step in a flow summary defined using `OptionalBarrier[name]`. An `OptionalBarrier` is "opt-out", by default
+   * data can flow freely through the step. Flow through the step can be explicity blocked by defining its node as a barrier.
+   */
   cached
   predicate optionalBarrier(Node node, string name) {
     FlowSummaryImpl::Private::Steps::summaryReadStep(_, TOptionalBarrier(name),