From 650b1db4b823155925877930d7800ac7f59cc334 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Mon, 20 Sep 2021 19:14:27 +0200
Subject: Add `print_verbose()` built-in function to print in verbose mode only

This can be used as a shorthand for:

    if OS.is_stdout_verbose():
        print("...")

Unlike `print_debug()`, this works in release builds too and can
be toggled off in debug builds.
---
 doc/classes/@GlobalScope.xml    | 5 +++++
 doc/classes/OS.xml              | 2 +-
 doc/classes/ProjectSettings.xml | 2 +-
 3 files changed, 7 insertions(+), 2 deletions(-)

(limited to 'doc/classes')

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index c47ce81651..0334bab32a 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -556,6 +556,11 @@
 				[b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.
 			</description>
 		</method>
+		<method name="print_verbose" qualifiers="vararg">
+			<description>
+				If verbose mode is enabled ([method OS.is_stdout_verbose] returning [code]true[/code]), converts one or more arguments of any type to string in the best way possible and prints them to the console.
+			</description>
+		</method>
 		<method name="printerr" qualifiers="vararg">
 			<description>
 				Prints one or more arguments to strings in the best way possible to standard error line.
diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml
index 305258c8c5..8954469b4d 100644
--- a/doc/classes/OS.xml
+++ b/doc/classes/OS.xml
@@ -338,7 +338,7 @@
 		<method name="is_stdout_verbose" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if the engine was executed with [code]-v[/code] (verbose stdout).
+				Returns [code]true[/code] if the engine was executed with the [code]--verbose[/code] or [code]-v[/code] command line argument, or if [member ProjectSettings.debug/settings/stdout/verbose_stdout] is [code]true[/code]. See also [method @GlobalScope.print_verbose].
 			</description>
 		</method>
 		<method name="is_userfs_persistent" qualifiers="const">
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 22ed14743a..3476d79559 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -432,7 +432,7 @@
 		<member name="debug/settings/stdout/print_gpu_profile" type="bool" setter="" getter="" default="false">
 		</member>
 		<member name="debug/settings/stdout/verbose_stdout" type="bool" setter="" getter="" default="false">
-			Print more information to standard output when running. It displays information such as memory leaks, which scenes and resources are being loaded, etc.
+			Print more information to standard output when running. It displays information such as memory leaks, which scenes and resources are being loaded, etc. This can also be enabled using the [code]--verbose[/code] or [code]-v[/code] command line argument, even on an exported project. See also [method OS.is_stdout_verbose] and [method @GlobalScope.print_verbose].
 		</member>
 		<member name="debug/settings/visual_script/max_call_stack" type="int" setter="" getter="" default="1024">
 			Maximum call stack in visual scripting, to avoid infinite recursion.
-- 
cgit v1.2.3