From 15b8a3d29408ade773291fca69d6aec18418c05c Mon Sep 17 00:00:00 2001
From: JordanHendersonMusic <j.henderson.music@outloook.com>
Date: Tue, 7 May 2024 13:59:04 +0100
Subject: [PATCH] SCDocs: Add documentation for DebugFrame

Creates a new file.
Also includes an example of how to construct a backtrace.
---
 HelpSource/Classes/DebugFrame.schelp | 69 ++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 HelpSource/Classes/DebugFrame.schelp

diff --git a/HelpSource/Classes/DebugFrame.schelp b/HelpSource/Classes/DebugFrame.schelp
new file mode 100644
index 00000000000..754c3c3be41
--- /dev/null
+++ b/HelpSource/Classes/DebugFrame.schelp
@@ -0,0 +1,69 @@
+class:: DebugFrame
+summary:: A representation of the call frame
+categories::  Core/Kernel
+
+Description::
+A representation of the call frame.
+Can be used to reconstruct a backtrace by using link::#-caller::.
+
+An instance can be acquired by calling link::Classes/Object#-getBackTrace::.
+While this is often not useful due to function inlining,
+it is useful when called on an link::Classes/Exception::,
+see the implementation of link::Classes/Exception#-reportError:: where a call to link::Classes/Object#-dumpBackTrace:: can be replaced by a call to link::Classes/Object#-getBackTrace:: and a call stack constructed manually.
+
+Instancemethods::
+
+method:: functionDef
+Returns a link::Classes/FunctionDef:: or a link::Classes/Method:: of the current function or method.
+
+method:: caller
+Returns another link::Classes/DebugFrame:: for the function that called this function.
+
+discussion::
+Can be used to make a back trace, but watch out for function inlining.
+code::
+(
+var debugFrame = { 1.0.getBackTrace }.();
+
+while{ debugFrame.isNil.not }{
+	var def = debugFrame.functionDef;
+	def.postln;
+	if(def.isKindOf(Method)){
+		File.readAllString(def.filenameSymbol.asString)[def.charPos..def.charPos + 200].post;
+		"...".postln;
+	} {
+		def.sourceCode.postln
+	};
+	"\n".post;
+	debugFrame = debugFrame.caller
+}
+)
+::
+
+method:: args
+Returns an link::Classes/Array:: of the argument's values, if there are no arguments, returns a link::Classes/Nil::.
+This does not contain the argument names, which must be accessed through the link::#-functionDef::.
+
+
+discussion::
+code::
+{ thisFunction.getBackTrace }.().args == nil;
+{ |a, b, c| thisFunction.getBackTrace }.().args == [nil, nil, nil];
+{ |a, b, c = 1| thisFunction.getBackTrace }.().args == [nil, nil, 1];
+{ |a, b, c = 1| thisFunction.getBackTrace }.(2, 3, c: 4).args == [2, 3, 4];
+::
+
+method:: vars
+Same as link::#-args:: but for the variables.
+discussion::
+code::
+{ thisFunction.getBackTrace }.().vars == nil
+{ var a; thisFunction.getBackTrace }.().vars == [nil]
+{ var a, b = 1; thisFunction.getBackTrace }.().vars == [nil, 1]
+::
+
+method:: address
+Returns a link::Classes/RawPointer::, rarely useful.
+
+method:: context
+Returns another link::Classes/DebugFrame:: of the compiling context, rarely useful.