Shared: update code comments explaining models-as-data format to include barriers and barrier guards

[owen-mc]

I have also copied some sections that were missing for some languages and corrected the explanation of neutral models. These changes have been done in separate commits.

[Copilot]

Pull request overview

Updates Models-as-Data / API-graph model documentation comments across several languages to describe barrier and barrier-guard model formats, and to refine the description of neutral models.

Changes:

• Document Barriers and BarrierGuards row formats in multiple MaD / ApiGraph model comment blocks.
• Add/expand documentation for barrier-guard condition columns (branch / acceptingvalue).
• Adjust neutral-model description text in ExternalFlow docs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
rust/ql/lib/codeql/rust/dataflow/internal/ModelsAsData.qll	Updates MaD format comment to include barriers/guards and neutrals.
ruby/ql/lib/codeql/ruby/frameworks/data/internal/ApiGraphModels.qll	Documents Barriers/BarrierGuards rows and branch meaning for API-graph models.
python/ql/lib/semmle/python/frameworks/data/internal/ApiGraphModels.qll	Documents Barriers/BarrierGuards rows and branch meaning for API-graph models.
javascript/ql/lib/semmle/javascript/frameworks/data/internal/ApiGraphModels.qll	Documents Barriers/BarrierGuards rows and branch meaning for API-graph models.
java/ql/lib/semmle/code/java/dataflow/ExternalFlow.qll	Documents Barriers/BarrierGuards and adjusts neutral-model description.
go/ql/lib/semmle/go/dataflow/ExternalFlow.qll	Documents Barriers/BarrierGuards and provenance; adjusts neutral-model description.
csharp/ql/lib/semmle/code/csharp/dataflow/internal/ExternalFlow.qll	Documents Barriers/BarrierGuards and adjusts neutral-model description.
cpp/ql/lib/semmle/code/cpp/dataflow/ExternalFlow.qll	Documents Barriers/BarrierGuards, acceptingvalue, and provenance.

Comments suppressed due to low confidence (3)

cpp/ql/lib/semmle/code/cpp/dataflow/ExternalFlow.qll:96

• Minor grammar: "In future" should be "In the future," (or similar) in this sentence.

 *    "false". In future "no-exception", "not-zero", "null", "not-null" may be
 *    supported.

rust/ql/lib/codeql/rust/dataflow/internal/ModelsAsData.qll:18

• The Neutrals row/description here doesn't match the rest of this module: the file defines neutralModel(string path, string kind, string provenance, ...) and later states kind can be source, sink, or summary. Please align the Neutrals row columns and the neutral explanation with the neutralModel predicate and its documented effect below.

 * - Neutrals:
 *   `package; type; name; signature; kind; provenance`
 *   A neutral is used to indicate that a callable is neutral with respect to flow (no summary).

rust/ql/lib/codeql/rust/dataflow/internal/ModelsAsData.qll:46

• This description says the barrier-guard branch column may support values like "no-exception"/"not-zero" in the future, but the barrierGuardModel documentation below states branch is either true or false (a branch selector). To avoid conflicting documentation, either keep branch restricted to true/false here or update the later barrierGuardModel docs to match the intended semantics.

 * 3. The `branch` column of barrier guard models specifies which branch of the
 *    guard is blocking flow. It can be "true" or "false". In future
 *    "no-exception", "not-zero", "null", "not-null" may be supported.

[hvitved]

Needs to be updated

[owen-mc]

Oops. Fixed in Rust: Fix columns for neutrals.

[hvitved]

In Rust it is called branch; we should probably align on this.

[owen-mc]

Let me know if you want me to do it in this PR. I think it's equally good as a follow-up or in the future when rust adopts the shared guards library.

[hvitved]

Perhaps simply rename it to acceptingvalue (I would actually prefer acceptingValue) so that all languages are aligned.

[owen-mc]

Hmm, now I look I see that all the dynamic languages call it branch. Shall I change it for all of them?

[michaelnebel]

Thank you for doing this!