From 1efe57848a00da704300d4c6c4448984e0d2d03c Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Wed, 16 Sep 2020 22:41:48 +0200
Subject: Improve documentation about VideoPlayer video formats

This closes https://github.com/godotengine/godot-docs/issues/4021.
---
 doc/classes/VideoPlayer.xml                      | 2 +-
 modules/theora/doc_classes/VideoStreamTheora.xml | 5 +++--
 modules/webm/doc_classes/VideoStreamWebm.xml     | 3 ++-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/classes/VideoPlayer.xml b/doc/classes/VideoPlayer.xml
index 91c8ad0a77..60f0a40159 100644
--- a/doc/classes/VideoPlayer.xml
+++ b/doc/classes/VideoPlayer.xml
@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		Control node for playing video streams using [VideoStream] resources.
-		Supported video formats are [url=https://www.webmproject.org/]WebM[/url] ([VideoStreamWebm]), [url=https://www.theora.org/]Ogg Theora[/url] ([VideoStreamTheora]), and any format exposed via a GDNative plugin using [VideoStreamGDNative].
+		Supported video formats are [url=https://www.webmproject.org/]WebM[/url] ([code].webm[/code], [VideoStreamWebm]), [url=https://www.theora.org/]Ogg Theora[/url] ([code].ogv[/code], [VideoStreamTheora]), and any format exposed via a GDNative plugin using [VideoStreamGDNative].
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/modules/theora/doc_classes/VideoStreamTheora.xml b/modules/theora/doc_classes/VideoStreamTheora.xml
index 92244a4d28..cb8852d5ef 100644
--- a/modules/theora/doc_classes/VideoStreamTheora.xml
+++ b/modules/theora/doc_classes/VideoStreamTheora.xml
@@ -4,7 +4,8 @@
 		[VideoStream] resource for Ogg Theora videos.
 	</brief_description>
 	<description>
-		[VideoStream] resource handling the [url=https://www.theora.org/]Ogg Theora[/url] video format with [code].ogv[/code] extension.
+		[VideoStream] resource handling the [url=https://www.theora.org/]Ogg Theora[/url] video format with [code].ogv[/code] extension. The Theora codec is less efficient than [VideoStreamWebm]'s VP8 and VP9, but it requires less CPU resources to decode. The Theora codec is decoded on the CPU.
+		[b]Note:[/b] While Ogg Theora videos can also have an [code].ogg[/code] extension, you will have to rename the extension to [code].ogv[/code] to use those videos within Godot.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -22,7 +23,7 @@
 			<argument index="0" name="file" type="String">
 			</argument>
 			<description>
-				Sets the Ogg Theora video file that this [VideoStreamTheora] resource handles. The [code]file[/code] name should have the [code].o[/code] extension.
+				Sets the Ogg Theora video file that this [VideoStreamTheora] resource handles. The [code]file[/code] name should have the [code].ogv[/code] extension.
 			</description>
 		</method>
 	</methods>
diff --git a/modules/webm/doc_classes/VideoStreamWebm.xml b/modules/webm/doc_classes/VideoStreamWebm.xml
index dfa04720cf..2edbc08cc8 100644
--- a/modules/webm/doc_classes/VideoStreamWebm.xml
+++ b/modules/webm/doc_classes/VideoStreamWebm.xml
@@ -4,7 +4,8 @@
 		[VideoStream] resource for WebM videos.
 	</brief_description>
 	<description>
-		[VideoStream] resource handling the [url=https://www.webmproject.org/]WebM[/url] video format with [code].webm[/code] extension.
+		[VideoStream] resource handling the [url=https://www.webmproject.org/]WebM[/url] video format with [code].webm[/code] extension. Both the VP8 and VP9 codecs are supported. The VP8 and VP9 codecs are more efficient than [VideoStreamTheora], but they require more CPU resources to decode (especially VP9). Both the VP8 and VP9 codecs are decoded on the CPU.
+		[b]Note:[/b] There are known bugs and performance issues with WebM video playback in Godot. If you run into problems, try using the Ogg Theora format instead: [VideoStreamTheora]
 	</description>
 	<tutorials>
 	</tutorials>
-- 
cgit v1.2.3