From bcff6fc367dc53ce8f11a059d545e8ca813923e1 Mon Sep 17 00:00:00 2001
From: Joban <2983844+jobansd@users.noreply.github.com>
Date: Fri, 14 Feb 2025 19:59:49 -0500
Subject: [PATCH] docs(WebGL API): enhance createShader(), compileShader(), and
 shaderSource() methods (#38008)

* docs(WebGL API): enhance createShader(), compileShader(), and shaderSource() methods

The WebGL documentation did not previously indicate the [`createShader()`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createShader) method may return `null` or that both [`compileShader()`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/compileShader) and [`shaderSource()`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/shaderSource) can throw `TypeError` exceptions.

This commit improves clarity and accuracy, ensuring developers are better informed about potential failure cases.

- Added amplifying information to the `type` parameter and details about possible `null` return value to [`createShader()`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createShader) method.
- Added an Exceptions section for [`compileShader()`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/compileShader) and [`shaderSource()`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/shaderSource) methods to document potential `TypeError` exception.

* Update files/en-us/web/api/webglrenderingcontext/createshader/index.md

---------

Co-authored-by: wbamberg <will@bootbonnet.ca>
---
 .../web/api/webglrenderingcontext/compileshader/index.md     | 5 +++++
 .../web/api/webglrenderingcontext/createshader/index.md      | 4 ++--
 .../web/api/webglrenderingcontext/shadersource/index.md      | 5 +++++
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/files/en-us/web/api/webglrenderingcontext/compileshader/index.md b/files/en-us/web/api/webglrenderingcontext/compileshader/index.md
index 9cbc7dfb16fb1c6..663dd8a873cc779 100644
--- a/files/en-us/web/api/webglrenderingcontext/compileshader/index.md
+++ b/files/en-us/web/api/webglrenderingcontext/compileshader/index.md
@@ -26,6 +26,11 @@ compileShader(shader)
 
 None ({{jsxref("undefined")}}).
 
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if the specified `shader` is not of type `WebGLShader`.
+
 ## Examples
 
 ```js
diff --git a/files/en-us/web/api/webglrenderingcontext/createshader/index.md b/files/en-us/web/api/webglrenderingcontext/createshader/index.md
index 70a9fb85dba7f98..701ab9761a861a3 100644
--- a/files/en-us/web/api/webglrenderingcontext/createshader/index.md
+++ b/files/en-us/web/api/webglrenderingcontext/createshader/index.md
@@ -23,11 +23,11 @@ createShader(type)
 ### Parameters
 
 - `type`
-  - : Either `gl.VERTEX_SHADER` or `gl.FRAGMENT_SHADER`
+  - : Either `gl.VERTEX_SHADER` or `gl.FRAGMENT_SHADER`. The {{domxref("WebGLRenderingContext")}} will set the `gl.INVALID_ENUM` error flag if an unacceptable value has been specified.
 
 ### Return value
 
-A new ({{domxref("WebGLShader")}}).
+A new {{domxref("WebGLShader")}} instance, or `null` if an error occurs creating the shader (for example, because `type` was an invalid value).
 
 ## Examples
 
diff --git a/files/en-us/web/api/webglrenderingcontext/shadersource/index.md b/files/en-us/web/api/webglrenderingcontext/shadersource/index.md
index 768803bbf242b1c..67803bfd4626f16 100644
--- a/files/en-us/web/api/webglrenderingcontext/shadersource/index.md
+++ b/files/en-us/web/api/webglrenderingcontext/shadersource/index.md
@@ -28,6 +28,11 @@ shaderSource(shader, source)
 
 None ({{jsxref("undefined")}}).
 
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if the specified `shader` is not of type `WebGLShader`.
+
 ## Examples
 
 ```js