From fe888a33378a985817c4c5d4dd67a5b98e4ef3b1 Mon Sep 17 00:00:00 2001 From: Marius Albrecht <64852250+MariusAlbrecht@users.noreply.github.com> Date: Thu, 28 Mar 2024 09:34:39 +0100 Subject: [PATCH] Docs fixes (#1478) * spec > dfg > AssignExpression > Case 1 mermaid syntax error * spec > dfg > NewExpression bulletpoint needs blank line * spec > dfg > ConditionalExpression mermaid doesnt render -> align code block quotes * spec > dfg > Reference > ControlFlowSensitiveDFGPass "Scheme:" missing one some bullets * spec > dfg > DoStatement bulletpoint needs blank line * spec > dfg > (While|For|If|Switch)Statement bulletpoint needs blank line * spec > dfg-function-summaries > example expl. bulletpoint/numList needs blank line * spec > dfg-function-summaries > exception throws bulletpoint needs blank line * spec > dfg-function-summaries > NewExpression Scheme shouldnt be bulletpoint * spec > dfg-function-summaries > ExpressionList typo --- docs/docs/CPG/specs/dfg-function-summaries.md | 2 ++ docs/docs/CPG/specs/dfg.md | 17 +++++++++++------ docs/docs/CPG/specs/eog.md | 5 +++-- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/docs/CPG/specs/dfg-function-summaries.md b/docs/docs/CPG/specs/dfg-function-summaries.md index 8bf268b9dd..a2871cb353 100644 --- a/docs/docs/CPG/specs/dfg-function-summaries.md +++ b/docs/docs/CPG/specs/dfg-function-summaries.md @@ -107,12 +107,14 @@ An example of a file could look as follows: ``` This file configures the following edges: + * For a method declaration in Java `java.util.List.addAll(int, java.util.Object)`, the parameter 1 flows to the base (i.e., the list object) * For a method declaration in Java `java.util.List.addAll(java.util.Object)`, the parameter 0 flows to the base (i.e., the list object) * For a function declaration in C `memcpy` (and thus also CXX `std::memcpy`), the parameter 1 flows to parameter 0. Note: If multiple function summaries match a method/function declaration (after the normal matching considering the language, local name of the function/method, signature if applicable and type hierarchy of the base object), we use the following routine to identify ideally a single entry: + 1. We filter for existing signatures since it's more precisely specified than the generic "catch all" without a signature-element. 2. We filter for the most precise class of the base. 3. If there are still multiple options, we take the longest signature. diff --git a/docs/docs/CPG/specs/dfg.md b/docs/docs/CPG/specs/dfg.md index af1138bf60..44f8bcfb26 100755 --- a/docs/docs/CPG/specs/dfg.md +++ b/docs/docs/CPG/specs/dfg.md @@ -91,7 +91,7 @@ flowchart LR ```mermaid flowchart LR A[assignment.rhs] -- DFG --> assignment.lhs; - subgraph S[If the ast parent is not a Block + subgraph S[If the ast parent is not a Block] direction LR assignment.rhs -- DFG --> assignment; end @@ -162,6 +162,7 @@ Scheme: ## NewExpression Interesting fields: + * `initializer: Expression`: The initializer of the expression. The `initializer` flows to the whole expression. @@ -207,7 +208,7 @@ Scheme: thenExpression -.- node; elseExpression -.- node; elseExpression -- DFG --> node; - ``` + ``` ## Reference @@ -269,7 +270,7 @@ The `ControlFlowSensitiveDFGPass` completely changes this behavior and accounts input -- DFG 4 --> R[/Node/]; R == next read of ==> refersTo; ``` -* For compound operators such as `+=, -=, *=, /=`, we have an incoming flow from the last writes to reference on the left hand side of the expression to the lhs. The lhs then flows to the whole expression. Also, the right hand side flows to the whole expression (if it's a read, this is processed separately). The data flows back to the lhs which is marked as the last write to the variable. *Attention: This potentially adds loops and can look like a branch. Needs to be handled with care in subsequent passes/analyses!* +* For compound operators such as `+=, -=, *=, /=`, we have an incoming flow from the last writes to reference on the left hand side of the expression to the lhs. The lhs then flows to the whole expression. Also, the right hand side flows to the whole expression (if it's a read, this is processed separately). The data flows back to the lhs which is marked as the last write to the variable. *Attention: This potentially adds loops and can look like a branch. Needs to be handled with care in subsequent passes/analyses!* Scheme: ```mermaid flowchart LR node -.- rhs; @@ -283,9 +284,9 @@ The `ControlFlowSensitiveDFGPass` completely changes this behavior and accounts node -- DFG 3 --> lhs; R[/Node/] == next read of ==> refersTo; ``` -* If the variable is assigned a value (a binary operator `var = rhs`), the right hand side flows to the variable. This is considered as a write operation. +* If the variable is assigned a value (a binary operator `var = rhs`), the right hand side flows to the variable. This is considered as a write operation. Scheme: ```mermaid - flowchart LR + flowchart LR node -.- rhs; node -.- lhs; lhs -.- refersTo; @@ -462,8 +463,8 @@ Scheme: ### DoStatement Interesting fields: -* `condition: Statement`: The condition that is evaluated before making the branching decision +* `condition: Statement`: The condition that is evaluated before making the branching decision Scheme: ```mermaid @@ -475,6 +476,7 @@ Scheme: ### WhileStatement Interesting fields: + * `condition: Statement`: The condition that is evaluated before making the branching decision * `conditionDeclaration: Statement`: A declaration containing the condition in the initializer, used instead of the condition @@ -490,6 +492,7 @@ Scheme: ### ForStatement Interesting fields: + * `condition: Statement`: The condition that is evaluated before making the branching decision * `conditionDeclaration: Statement`: A declaration containing the condition in the initializer, used instead of the condition. @@ -506,6 +509,7 @@ Scheme: ### IfStatement Interesting fields: + * `condition: Statement`: The condition that is evaluated before making the branching decision * `conditionDeclaration: Statement`: A declaration containing the condition in the initialize, used instead of the condition. @@ -521,6 +525,7 @@ Scheme: ### SwitchStatement Interesting fields: + * `selector: Statement`: The expression that is evaluated before making the branching decision * `selectorDeclaration: Statement`: A declaration containing the selector in the initializer, used instead of the selector. diff --git a/docs/docs/CPG/specs/eog.md b/docs/docs/CPG/specs/eog.md index 64bb47c19c..d27fae5eb5 100644 --- a/docs/docs/CPG/specs/eog.md +++ b/docs/docs/CPG/specs/eog.md @@ -365,6 +365,7 @@ flowchart LR Throwing of exceptions is modelled as unary operation. The EOG continues at an exception catching structure or a function that does a re-throw. Interesting fields: + * `input: Expression`: Exception to be thrown for exception handling. Scheme: @@ -501,7 +502,7 @@ Interesting fields: * `initializer: Expression`: To be evaluated before creating a new object. -* Scheme: +Scheme: ```mermaid flowchart LR classDef outer fill:#fff,stroke:#ddd,stroke-dasharray:5 5; @@ -527,7 +528,7 @@ flowchart LR ``` ## ExpressionList -List of several expressions that aer evaluated sequentially. The resulting value is the last evaluated expression. +List of several expressions that are evaluated sequentially. The resulting value is the last evaluated expression. Interesting fields: