Merge pull request #111 from joernio/andrei/docs/frontend-call-structure

[Docs] Add call modelling for Java, Javascript and Python

docs.joern.io/.gitignore

@@ -1,3 +1,4 @@
 resources
 *.lock
 themes
+public/

docs.joern.io/content/frontends/java.md

@@ -21,4 +21,51 @@ The following arguments are specific to the `javasrc2cpg` frontend.
 | `cache-jdk-type-solver` | Re-use the JDK type solver between scans | - | `--cache-jdk-type-solver` | `true` |
 | `keep-type-arguments` | Type full names of variables keep their type arguments | - | `--keep-type-arguments` | `true` |
 | `no-dummyTypes` | Disables the generation of dummy types during type propagation | - | `--no-dummyTypes` | `true` |
-| `type-prop-iterations` | Maximum iterations of type propagation | `Integer` | `--type-prop-iterations 2` | `true` |
+| `type-prop-iterations` | Maximum iterations of type propagation | `Integer` | `--type-prop-iterations 2` | `true` |
+
+### Calls
+The section below shows how different call ASTs are modelled in Java.
+
+The following is a simple call in Java:
+```java
+class Foo {
+  public void bar(String param1, Integer param2, String param3) {
+    s.length()
+  }
+
+  public void baz() {
+    bar("1", 2, "3")
+  }
+}
+```
+![Image of a simple call AST for a function in the same class in Java](/images/java_call.png)
+The structure of the call AST:
+```
+CallNode
+├── Receiver: this
+├── MethodName: bar
+└── Arguments
+    ├── Argument[0]: this 
+    ├── Argument[1]: param1
+    ├── Argument[2]: param2
+    └── Argument[3]: parma3
+```
+Note that the method signature in the Java code only has three arguments, but the call AST has four. There is an implicit argument that is added in the 0th position, which is the `receiver` of the call node. In this case since the call is invoking a method defined in the same class, so an implicit `this` argument is added at `arg[0]` as the `receiver` of the call. Note that dynamic methods (i.e methods without the `static` modifier) also have a `this` 0th parameter that lines up with the `this` 0th argument in the `CallNode`.
+
+The following is a static member call in Java:
+```java
+class Foo {
+  public void bar() {
+    Baz.bazFunc("1", 2, "3");
+  }
+}
+
+class Baz {
+  public static int bazFunc(String param1, Integer param2, String param3) {
+    return 1
+  }
+}
+```
+![Image of a simple call AST for a static function in a different class in Java](/images/java_static_call.png)
+
+The structure of the call AST for the static function is the same as it is for the simple call above, the only difference is that the `receiver` (and thus `arg[0]`) of the call has now changed to `Baz` since the method being invoked is defined in the `Baz` class.

docs.joern.io/content/frontends/javascript.md

@@ -11,4 +11,49 @@ The following arguments are specific to the `jssrc2cpg` frontend.
 | - | - | - | - | - |
 | `no-tsTypes` | Disable generation of types via `TypeScript` | - | `--no-tsTypes` | `true` |
 | `no-dummyTypes` | Disables the generation of dummy types during type propagation | - | `--no-dummyTypes` | `true` |
-| `type-prop-iterations` | Maximum iterations of type propagation | `Integer` | `--type-prop-iterations 2` | `true` |
+| `type-prop-iterations` | Maximum iterations of type propagation | `Integer` | `--type-prop-iterations 2` | `true` |
+
+### Calls
+The section below shows how different call ASTs are modelled in JavaScript.
+```javascript
+class Foo {
+  bar(param1, param2, param3) {
+    // do something
+  }
+
+  baz(param1, param2, param3) {
+    bar("1", 2, "3")
+  }
+}
+```
+![Image of a simple call AST for a function in the same class in JavaScript](/images/javascript_call.png)
+The structure of the call AST:
+```
+CallNode
+├── Receiver: this.bar
+├── MethodName: bar
+└── Arguments
+    ├── Argument[-1]: bar
+    ├── Argument[0]: this 
+    ├── Argument[1]: param1
+    ├── Argument[2]: param2
+    └── Argument[3]: parma3
+```
+Simple calls are modelled slightly different in dynamic languages (such as JavaScript) when compared to static languages. In dynamic languages `arg[0]` is no longer the receiver of the call, but instead is the object that holds the property which is the receiver of the call. There is also a 5th argument introduced, which is `arg[-1]`.
+
+The following is a static member call in JavaScript:
+```javascript
+class Foo {
+  bar(param1, param2, param3) {
+    Baz.baz("1", 2, "3")
+  }
+}
+
+class Baz {
+  static baz(param1, param2, param3) {
+    // do something
+  }
+}
+```
+![Image of a simple call AST for a static function in a different class in JavaScript](/images/javascript_static_call.png)
+The structure of the call AST is mostly the same as for a simple call, with the receiver of the call now just being `Baz.baz` instead of `self.bar`.

docs.joern.io/content/frontends/python.md

@@ -15,4 +15,45 @@ The following arguments are specific to the `pysrc2cpg` frontend.
 | `ignore-paths` | Ignores specified paths from analysis. If not absolute it is interpreted relative to `input-dir` | `List<String>` | `--ignore-paths "/path/to/ignore1, /path/to/ignore2"` | `false` |
 | `ignore-dir-names` | Exclude all files where the relative path from `input-dir` contains at least one of the names specified | `List<String>` | `--ignore-dir-names "rel/path/ignore1, rel/path/ignore2"` | `true` |
 | `no-dummyTypes` | Disables the generation of dummy types during type propagation | - | `--no-dummyTypes` | `true` |
-| `type-prop-iterations` | Maximum iterations of type propagation | `Integer` | `--type-prop-iterations 2` | `true` |
+| `type-prop-iterations` | Maximum iterations of type propagation | `Integer` | `--type-prop-iterations 2` | `true` |
+
+### Calls
+The section below shows how different call ASTs are modelled in Python.
+
+The following is a simple call in Python
+```python
+class Foo:
+  def bar(self, param1, param2, param3):
+    pass 
+
+  def baz():
+    self.bar("1", 2, "3")
+```
+![Image of a simple call AST for a function in the same class in Python](/images/python_call.png)
+The structure of the call AST:
+```
+CallNode
+├── Receiver: self.bar
+├── MethodName: bar
+└── Arguments
+    ├── Argument[-1]:self.bar 
+    ├── Argument[0]: self 
+    ├── Argument[1]: param1
+    ├── Argument[2]: param2
+    └── Argument[3]: parma3
+```
+Simple calls are modelled slightly different in dynamic languages (such as Python) when compared to static languages. In dynamic languages `arg[0]` is no longer the receiver of the call, but instead is the object that holds the property which is the receiver of the call. There is also a 5th argument introduced, which is `arg[-1]`. In Python, the `self` argument is the same as the `this` argument in other languages.
+
+The following is a member call in Python
+```python
+class Foo:
+  def bar(self):
+    bazObj = Baz()
+    bazObj.baz("1", 2, "3")
+
+class Baz:
+  def baz(self, param1, param2, param3):
+    pass
+```
+![Image of a simple call AST for a function in a different class in Python](/images/python_member_call.png)
+The structure of the call AST is mostly the same as for a simple call, with the receiver of the call now just being `Baz.baz` instead of `self.bar`.