From b26fc66a60a47a1bbe69982f411eabc567caed54 Mon Sep 17 00:00:00 2001
From: Luis Rascao <luis.rascao@miniclip.com>
Date: Tue, 17 Sep 2019 08:47:02 +0100
Subject: Improve dynamic tracing of function calls documentation

---
 erts/emulator/beam/erlang_dtrace.d                 |  6 +--
 lib/runtime_tools/examples/function-calls.d        | 46 ++++++++++++++++++++++
 .../examples/function-calls.systemtap              | 46 ++++++++++++++++++++++
 3 files changed, 95 insertions(+), 3 deletions(-)

diff --git a/erts/emulator/beam/erlang_dtrace.d b/erts/emulator/beam/erlang_dtrace.d
index 8792138d53..8864a8ec84 100644
--- a/erts/emulator/beam/erlang_dtrace.d
+++ b/erts/emulator/beam/erlang_dtrace.d
@@ -176,7 +176,7 @@ provider erlang {
      * Fired whenever a user function returns.
      *
      * @param p the PID (string form) of the process
-     * @param mfa the m:f/a of the function
+     * @param mfa the m:f/a of the function being returned from
      * @param depth the stack depth
      */
     probe function__return(char *p, char *mfa, int depth);
@@ -193,7 +193,7 @@ provider erlang {
      * Fired whenever a Built In Function returns.
      *
      * @param p the PID (string form) of the process
-     * @param mfa the m:f/a of the function
+     * @param mfa the m:f/a of the function being returned from
      */
     probe bif__return(char *p, char *mfa);
 
@@ -209,7 +209,7 @@ provider erlang {
      * Fired whenever a Native Function returns.
      *
      * @param p the PID (string form) of the process
-     * @param mfa the m:f/a of the function
+     * @param mfa the m:f/a of the function being returned from
      */
     probe nif__return(char *p, char *mfa);
 
diff --git a/lib/runtime_tools/examples/function-calls.d b/lib/runtime_tools/examples/function-calls.d
index f8ca388228..a51ff51253 100644
--- a/lib/runtime_tools/examples/function-calls.d
+++ b/lib/runtime_tools/examples/function-calls.d
@@ -19,39 +19,85 @@
  * %CopyrightEnd%
  */
 
+/**
+ * Triggered on local function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ * @param arg2 depth
+ */
 erlang*:::local-function-entry
 {
     printf("pid %s enter (local)  %s depth %d\n",
 	   copyinstr(arg0), copyinstr(arg1), arg2);
 }
 
+/**
+ * Triggered on global function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ * @param arg2 depth
+ */
 erlang*:::global-function-entry
 {
     printf("pid %s enter (global)  %s depth %d\n",
 	   copyinstr(arg0), copyinstr(arg1), arg2);
 }
 
+/**
+ * Triggered upon function return, either global or
+ * local
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the returned from function
+ * @param arg2 depth
+ */
 erlang*:::function-return
 {
     printf("pid %s return %s depth %d\n",
 	   copyinstr(arg0), copyinstr(arg1), arg2);
 }
 
+/**
+ * Triggered on built-in function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ */
 erlang*:::bif-entry
 {
     printf("pid %s BIF entry  mfa %s\n", copyinstr(arg0), copyinstr(arg1));
 }
 
+/**
+ * Triggered on built-in function return
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the returned from function
+ */
 erlang*:::bif-return
 {
     printf("pid %s BIF return mfa %s\n", copyinstr(arg0), copyinstr(arg1));
 }
 
+/**
+ * Triggered on native function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ */
 erlang*:::nif-entry
 {
     printf("pid %s NIF entry  mfa %s\n", copyinstr(arg0), copyinstr(arg1));
 }
 
+/**
+ * Triggered upon native function return
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the returned from function
+ */
 erlang*:::nif-return
 {
     printf("pid %s NIF return mfa %s\n", copyinstr(arg0), copyinstr(arg1));
diff --git a/lib/runtime_tools/examples/function-calls.systemtap b/lib/runtime_tools/examples/function-calls.systemtap
index 6bb173b3ec..8f748ce0d1 100644
--- a/lib/runtime_tools/examples/function-calls.systemtap
+++ b/lib/runtime_tools/examples/function-calls.systemtap
@@ -29,39 +29,85 @@
  *       to your environment.
  */
 
+/**
+ * Triggered on local function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ * @param arg2 depth
+ */
 probe process("beam.smp").mark("local-function-entry")
 {
     printf("pid %s enter (local) %s depth %d\n",
 	   user_string($arg1), user_string($arg2), $arg3);
 }
 
+/**
+ * Triggered on global function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ * @param arg2 depth
+ */
 probe process("beam.smp").mark("global-function-entry")
 {
     printf("pid %s enter (global)  %s depth %d\n",
 	   user_string($arg1), user_string($arg2), $arg3);
 }
 
+/**
+ * Triggered upon function return, either global or
+ * local
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the returned from function
+ * @param arg2 depth
+ */
 probe process("beam.smp").mark("function-return")
 {
     printf("pid %s return %s depth %d\n",
 	   user_string($arg1), user_string($arg2), $arg3);
 }
 
+/**
+ * Triggered on built-in function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ */
 probe process("beam.smp").mark("bif-entry")
 {
     printf("pid %s BIF entry  mfa %s\n", user_string($arg1), user_string($arg2));
 }
 
+/**
+ * Triggered on built-in function return
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the returned from function
+ */
 probe process("beam.smp").mark("bif-return")
 {
     printf("pid %s BIF return mfa %s\n", user_string($arg1), user_string($arg2));
 }
 
+/**
+ * Triggered on native function entry
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the function
+ */
 probe process("beam.smp").mark("nif-entry")
 {
     printf("pid %s NIF entry  mfa %s\n", user_string($arg1), user_string($arg2));
 }
 
+/**
+ * Triggered upon native function return
+ *
+ * @param arg0 pid
+ * @param arg1 MFA of the returned from function
+ */
 probe process("beam.smp").mark("nif-return")
 {
     printf("pid %s NIF return mfa %s\n", user_string($arg1), user_string($arg2));
-- 
cgit v1.2.1