feat: In-editor class reference documentation

.gitignore

@@ -1,10 +1,10 @@
 # Project-related
-project/addons
+project/addons/
 project/export_presets.cfg
-project/.vscode
-project/reports
+project/.vscode/
+project/reports/
 
-src/sdk_version.gen.h
+src/gen/
 
 # Godot auto generated files
 project/.godot/

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - Renamed the **Sentry/Config** category in Project Settings to **Sentry/Options** ([#119](https://github.com/getsentry/sentry-godot/pull/119)). This change invalidates all previously set options in project settings. To migrate, open your `project.godot` file in a text editor and replace all instances of "sentry/config" with "sentry/options".
 
+### Features
+
+- In-editor class reference documentation ([#104](https://github.com/getsentry/sentry-godot/pull/104))
+
 ### Fixes
 
 - Fix `user.id` not assigned to `installation_id` by default ([#118](https://github.com/getsentry/sentry-godot/pull/118))

SConstruct

@@ -46,7 +46,9 @@ version_header_content = """/* DO NOT EDIT - generated by SConstruct */
 #endif // SENTRY_GODOT_SDK_VERSION_GEN_H
 """.format(version=VERSION, git_sha=git_sha)
 
-with open("src/sdk_version.gen.h", "w") as f:
+if not os.path.exists("src/gen/"):
+    os.mkdir("src/gen/")
+with open("src/gen/sdk_version.gen.h", "w") as f:
     f.write(version_header_content)
 
 
@@ -224,6 +226,14 @@ sources += Glob("src/sentry/*.cpp")
 if env["platform"] in ["linux", "windows", "macos"]:
     sources += Glob("src/sentry/native/*.cpp")
 
+# Generate documentation data.
+if env["target"] in ["editor", "template_debug"]:
+    try:
+        doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
+        sources.append(doc_data)
+    except AttributeError:
+        print("Not including class reference as we're targeting a pre-4.3 baseline.")
+
 build_type = "release" if env["target"] == "template_release" else "debug"
 
 if env["platform"] == "macos":

doc_classes/SentryConfiguration.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="SentryConfiguration" inherits="Node" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://github.com/raw/godotengine/godot/master/doc/class.xsd">
+	<brief_description>
+		Base class for user configuration script in Sentry SDK.
+	</brief_description>
+	<description>
+		Allows configuring Sentry SDK from GDScript. The [method _configure] method is called just before Sentry SDK initializes.
+		To define a configuration script, create a new script that extends the [SentryConfiguration] class. Then, assign your configuration script in the Project Settings under the [b]Sentry[/b] category.
+		[b]Important[/b]: If a user configuration script is assigned, SDK initialization will be delayed until [b]ScriptServer[/b] becomes available during game startup.
+		[codeblock]
+		extends SentryConfiguration
+
+		func _configure(options: SentryOptions):
+		    if OS.is_debug_build():
+		        options.environment = "debug"
+		        options.debug = true
+		    options.release = "[email protected]"
+		    options.before_send = _process_event
+		    options.on_crash = _process_event
+
+		func _process_event(event: SentryEvent) -> SentryEvent:
+		    if event.environment == "debug":
+		        # Discard event if running in a debug build.
+		        return null
+		    if event.message.contains("Bruno"):
+		        # Remove sensitive information from the event.
+		        event.message = event.message.replace("Bruno", "REDACTED")
+		    return event
+		[/codeblock]
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="_configure" qualifiers="virtual">
+			<return type="void" />
+			<param index="0" name="options" type="SentryOptions" />
+			<description>
+				Called just before the Sentry SDK initializes. You can override SDK [param options] here and register [member SentryOptions.before_send] and [member SentryOptions.on_crash] callbacks if needed.
+			</description>
+		</method>
+	</methods>
+</class>

doc_classes/SentryEvent.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="SentryEvent" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://github.com/raw/godotengine/godot/master/doc/class.xsd">
+	<brief_description>
+	</brief_description>
+	<description>
+		Events are the core data sent by SDKs to the Sentry server. An event consists of simple data properties that capture key details about an occurrence. Typically, an event represents an error or exception and corresponds to a single transmission of data to the Sentry server. Events show up as issues on your issue stream, with the [member message] as the issue name.
+		[SentryEvent] can be created with the [method SentrySDK.create_event] method, and then captured with [method SentrySDK.capture_event].
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_tag">
+			<return type="String" />
+			<param index="0" name="key" type="String" />
+			<description>
+				Returns the value of the tag with the specified [param key].
+			</description>
+		</method>
+		<method name="remove_tag">
+			<return type="void" />
+			<param index="0" name="key" type="String" />
+			<description>
+				Removes the tag with the specified [param key].
+			</description>
+		</method>
+		<method name="set_tag">
+			<return type="void" />
+			<param index="0" name="key" type="String" />
+			<param index="1" name="value" type="String" />
+			<description>
+				Sets a tag with the specified [param key] to the given [param value].
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="dist" type="String" setter="set_dist" getter="get_dist" default="&quot;&quot;">
+			The application's distribution. Defaults to the value set in [member SentryOptions.dist].
+			Distributions are used to disambiguate build or deployment variants of the same release of an application.
+		</member>
+		<member name="environment" type="String" setter="set_environment" getter="get_environment" default="&quot;&quot;">
+			Environments indicate where an error occurred, such as in a release export, headless server, QA build, or another deployment. See [member SentryOptions.environment].
+		</member>
+		<member name="id" type="String" setter="" getter="get_id" default="&quot;&quot;">
+			Hexadecimal string representing a UUID version 4 value. Automatically set by the SDK.
+		</member>
+		<member name="level" type="int" setter="set_level" getter="get_level" enum="SentrySDK.Level" default="1">
+			The record severity level of the event. Defaults to [code]LEVEL_ERROR[/code]. See [enum SentrySDK.Level].
+		</member>
+		<member name="logger" type="String" setter="set_logger" getter="get_logger" default="&quot;&quot;">
+			The name of the logger which created the record.
+		</member>
+		<member name="message" type="String" setter="set_message" getter="get_message" default="&quot;&quot;">
+			The log message that describes an event or error.
+		</member>
+		<member name="platform" type="String" setter="" getter="get_platform" default="&quot;&quot;">
+			Represents the platform the SDK is submitting from. Automatically set by the SDK.
+		</member>
+		<member name="release" type="String" setter="set_release" getter="get_release" default="&quot;&quot;">
+			The release version of the application. Defaults to a value based on [member SentryOptions.release] option.
+			Release versions must be unique across all projects in your organization. This value can be the Git SHA for the given project, or a product identifier with a semantic version (suggested format [email protected]).
+		</member>
+		<member name="timestamp" type="String" setter="set_timestamp" getter="get_timestamp" default="&quot;&quot;">
+			Indicates when the event was created in the Sentry SDK. Automatically set by the SDK.
+		</member>
+	</members>
+</class>

doc_classes/SentryLoggerLimits.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="SentryLoggerLimits" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://github.com/raw/godotengine/godot/master/doc/class.xsd">
+	<brief_description>
+		Specifies throttling limits for the error logger.
+	</brief_description>
+	<description>
+		These limits govern the behavior of throttling and are used to prevent the SDK from sending too many non-critical and repeating error events. See also [SentryOptions].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="events_per_frame" type="int" setter="set_events_per_frame" getter="get_events_per_frame" default="5">
+			Specifies the maximum number of error events to send per processed frame. If exceeded, no further errors will be captured until the next frame.
+			This serves as a safety measure to prevent the SDK from overloading a single frame.
+		</member>
+		<member name="repeated_error_window_ms" type="int" setter="set_repeated_error_window_ms" getter="get_repeated_error_window_ms" default="1000">
+			Specifies the minimum time interval in milliseconds between two identical errors. If exceeded, no further errors from the same line of code will be captured until the next interval.
+		</member>
+		<member name="throttle_events" type="int" setter="set_throttle_events" getter="get_throttle_events" default="20">
+			Specifies the maximum number of events allowed within a sliding time window of [member throttle_window_ms] milliseconds. If exceeded, errors will be captured as breadcrumbs only until capacity is freed.
+		</member>
+		<member name="throttle_window_ms" type="int" setter="set_throttle_window_ms" getter="get_throttle_window_ms" default="10000">
+			Specifies the time window in milliseconds for [member throttle_events].
+		</member>
+	</members>
+</class>

doc_classes/SentryOptions.xml

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="SentryOptions" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://github.com/raw/godotengine/godot/master/doc/class.xsd">
+	<brief_description>
+		Contains Sentry SDK options.
+	</brief_description>
+	<description>
+		Defines options for the Sentry SDK. These options can be modified in the Project Settings under the [b]Sentry[/b] category or through a user configuration script. See [SentryConfiguration] for details on creating such a script.
+		To learn more, visit [url=https://docs.sentry.io/platforms/godot/configuration/options/]Options documentation[/url].
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="attach_log" type="bool" setter="set_attach_log" getter="is_attach_log_enabled" default="true">
+			If [code]true[/code], the SDK will attach the Godot log file to the event.
+		</member>
+		<member name="before_send" type="Callable" setter="set_before_send" getter="get_before_send" default="Callable()">
+			If assigned, this callback runs before a message or error event is sent to Sentry. It takes [SentryEvent] as a parameter and return either the same event object, with or without modifications, or [code]null[/code] to skip reporting the event. You can assign it in a [SentryConfiguration] script.
+			[codeblock]
+			func _before_send(event: SentryEvent) -&gt; SentryEvent:
+			    if event.environment == "editor_dev_run":
+			        # Discard event if running from the editor.
+			        return null
+			    if event.message.contains("Bruno"):
+			        # Remove sensitive information from the event.
+			        event.message = event.message.replace("Bruno", "REDACTED")
+			    return event
+			[/codeblock]
+			To learn more, visit [url=https://docs.sentry.io/platforms/godot/configuration/filtering/]Filtering documentation[/url]. Also, check out [url=https://docs.sentry.io/platforms/godot/data-management/sensitive-data/]Scrubbing Sensitive Data[/url].
+		</member>
+		<member name="debug" type="bool" setter="set_debug_enabled" getter="is_debug_enabled" default="true">
+			If [code]true[/code], the SDK will print useful debugging information to standard output. These messages do not appear in the Godot console but can be seen when launching Godot from a terminal.
+		</member>
+		<member name="disabled_in_editor" type="bool" setter="set_disabled_in_editor" getter="is_disabled_in_editor" default="true">
+			If [code]true[/code], the SDK will not initialize in the Godot editor.
+		</member>
+		<member name="dist" type="String" setter="set_dist" getter="get_dist" default="&quot;&quot;">
+			The application's distribution. Distributions are used to disambiguate build or deployment variants of the same release of an application.
+		</member>
+		<member name="dsn" type="String" setter="set_dsn" getter="get_dsn" default="&quot;&quot;">
+			Data Source Name (DSN): Specifies where the SDK should send the events. If this value is not provided, the SDK will try to read it from the [code]SENTRY_DSN[/code] environment variable. If that variable also does not exist, the SDK will just not send any events.
+		</member>
+		<member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true">
+			If [code]false[/code], the SDK will not initialize. This is useful for temporarily disabling the SDK in the Project Settings, or in a [SentryConfiguration] script.
+		</member>
+		<member name="environment" type="String" setter="set_environment" getter="get_environment" default="&quot;editor_dev&quot;">
+			Environments indicate where an error occurred, such as in a release export, headless server, QA build, or another deployment. The SDK automatically detects Godot-specific environments, such as [code]headless_server[/code] and [code]export_release[/code], but you can also assign it in a [SentryConfiguration] script.
+			To learn more, visit [url=https://docs.sentry.io/platforms/godot/configuration/environments/]Environments documentation[/url].
+		</member>
+		<member name="error_logger_breadcrumb_mask" type="int" setter="set_error_logger_breadcrumb_mask" getter="get_error_logger_breadcrumb_mask" enum="SentryOptions.GodotErrorMask" is_bitfield="true" default="15">
+			Specifies the types of errors captured as breadcrumbs. Accepts a single value or a bitwise combination of [enum GodotErrorMask] masks.
+		</member>
+		<member name="error_logger_enabled" type="bool" setter="set_error_logger_enabled" getter="is_error_logger_enabled" default="true">
+			If [code]true[/code], the SDK will capture logged errors as events and/or breadcrumbs, as defined by [member error_logger_event_mask] and [member error_logger_breadcrumb_mask]. Crashes are always captured.
+		</member>
+		<member name="error_logger_event_mask" type="int" setter="set_error_logger_event_mask" getter="get_error_logger_event_mask" enum="SentryOptions.GodotErrorMask" is_bitfield="true" default="13">
+			Specifies the types of errors captured as events. Accepts a single value or a bitwise combination of [enum GodotErrorMask] masks.
+		</member>
+		<member name="error_logger_include_source" type="bool" setter="set_error_logger_include_source" getter="is_error_logger_include_source_enabled" default="true">
+			If [code]true[/code], the SDK will include the surrounding source code of logged errors, if available in the exported project.
+		</member>
+		<member name="error_logger_limits" type="SentryLoggerLimits" setter="set_error_logger_limits" getter="get_error_logger_limits">
+			Defines throttling limits for the error logger. These limits are used to prevent the SDK from sending too many non-critical and repeating error events. See [SentryLoggerLimits].
+		</member>
+		<member name="max_breadcrumbs" type="int" setter="set_max_breadcrumbs" getter="get_max_breadcrumbs" default="100">
+			Maximum number of breadcrumbs to send with an event. You should be aware that Sentry has a maximum payload size and any events exceeding that payload size will be dropped.
+		</member>
+		<member name="on_crash" type="Callable" setter="set_on_crash" getter="get_on_crash" default="Callable()">
+			If assigned, this callback runs before a crash event is sent to Sentry. In contrast to [member before_send], it is only called when a crash occurred. It takes [SentryEvent] as a parameter and return either the same event object, with or without modifications, or [code]null[/code] to skip reporting the event. You can assign it in a [SentryConfiguration] script.
+			[codeblock]
+			func _on_crash(event: SentryEvent) -&gt; SentryEvent:
+			    if event.environment == "editor_dev_run":
+			        # Discard event if running from the editor.
+			        return null
+			    if event.message.contains("Bruno"):
+			        # Remove sensitive information from the event.
+			        event.message = event.message.replace("Bruno", "REDACTED")
+			    return event
+			[/codeblock]
+			To learn more, visit [url=https://docs.sentry.io/platforms/godot/configuration/filtering/]Filtering documentation[/url].
+		</member>
+		<member name="release" type="String" setter="set_release" getter="get_release" default="&quot;{app_name}@{app_version}&quot;">
+			Release version of the application. This value must be unique across all projects in your organization. Suggested format is [code][email protected][/code].
+			You can use the [code]{app_name}[/code] and [code]{app_version}[/code] placeholders to insert the application name and version from the Project Settings.
+		</member>
+		<member name="sample_rate" type="float" setter="set_sample_rate" getter="get_sample_rate" default="1.0">
+			Configures the sample rate for error events, in the range of 0.0 to 1.0. The default is 1.0, which means that 100% of error events will be sent. If set to 0.1, only 10% of error events will be sent. Events are picked randomly.
+		</member>
+		<member name="send_default_pii" type="bool" setter="set_send_default_pii" getter="is_send_default_pii_enabled" default="false">
+			If [code]true[/code], the SDK will include PII (Personally Identifiable Information) with the events.
+		</member>
+	</members>
+	<constants>
+		<constant name="MASK_NONE" value="0" enum="GodotErrorMask" is_bitfield="true">
+			No logger errors will be captured.
+		</constant>
+		<constant name="MASK_ERROR" value="1" enum="GodotErrorMask" is_bitfield="true">
+			Native errors will be captured. These are typically C++ errors, which may also originate from a script.
+		</constant>
+		<constant name="MASK_WARNING" value="2" enum="GodotErrorMask" is_bitfield="true">
+			Warnings will be captured.
+		</constant>
+		<constant name="MASK_SCRIPT" value="4" enum="GodotErrorMask" is_bitfield="true">
+			Script errors will be captured.
+		</constant>
+		<constant name="MASK_SHADER" value="8" enum="GodotErrorMask" is_bitfield="true">
+			Shader errors will be captured.
+		</constant>
+	</constants>
+</class>