diff --git a/src/compiler/glsl/gl_nir_link_atomics.c b/src/compiler/glsl/gl_nir_link_atomics.c
index 2b060513a60..62f04af9d87 100644
--- a/src/compiler/glsl/gl_nir_link_atomics.c
+++ b/src/compiler/glsl/gl_nir_link_atomics.c
@@ -27,10 +27,9 @@
 #include "compiler/glsl/ir_uniform.h" /* for gl_uniform_storage */
 #include "main/context.h"
 
-/* This file do the common link for GLSL atomic counter uniforms, using NIR,
+/**
+ * This file do the common link for GLSL atomic counter uniforms, using NIR,
  * instead of IR as the counter-part glsl/link_uniforms.cpp
- *
- * Also note that this is tailored for ARB_gl_spirv needs and particularities
  */
 
 struct active_atomic_counter_uniform {
diff --git a/src/compiler/glsl/gl_nir_link_uniform_blocks.c b/src/compiler/glsl/gl_nir_link_uniform_blocks.c
index 28faa7e7626..53f03fe2a80 100644
--- a/src/compiler/glsl/gl_nir_link_uniform_blocks.c
+++ b/src/compiler/glsl/gl_nir_link_uniform_blocks.c
@@ -27,11 +27,11 @@
 #include "linker_util.h"
 #include "main/mtypes.h"
 
-/* Summary: This file contains code to do a nir-based linking for uniform
- * blocks. This includes ubos and ssbos.  Note that it is tailored to
- * ARB_gl_spirv needs and particularities.
+/**
+ * This file contains code to do a nir-based linking for uniform blocks. This
+ * includes ubos and ssbos.
  *
- * More details:
+ * For the case of ARB_gl_spirv there are some differences compared with GLSL:
  *
  * 1. Linking doesn't use names: GLSL linking use names as core concept. But
  *    on SPIR-V, uniform block name, fields names, and other names are
@@ -67,8 +67,9 @@
  *    RESOLVED.  Pick (c), but also allow debug names to be returned if an
  *    implementation wants to."
  *
- * This implemention doesn't care for the names, as the main objective is
- * functional, and not support optional debug features.
+ * When linking SPIR-V shaders this implemention doesn't care for the names,
+ * as the main objective is functional, and not support optional debug
+ * features.
  *
  * 2. Terminology: this file handles both UBO and SSBO, including both as
  *    "uniform blocks" analogously to what is done in the GLSL (IR) path.
@@ -80,11 +81,11 @@
  *       <skip>
  *       buffer  blockN { ... } ...;  -> Uniform, with BufferBlock decoration"
  *
- * 3. Explicit data: The code assumes that all structure members have an
- *    Offset decoration, all arrays have an ArrayStride and all matrices have
- *    a MatrixStride, even for nested structures. That way we don’t have to
- *    worry about the different layout modes. This is explicitly required in
- *    the SPIR-V spec:
+ * 3. Explicit data: for the SPIR-V path the code assumes that all structure
+ *    members have an Offset decoration, all arrays have an ArrayStride and
+ *    all matrices have a MatrixStride, even for nested structures. That way
+ *    we don’t have to worry about the different layout modes. This is
+ *    explicitly required in the SPIR-V spec:
  *
  *    "Composite objects in the UniformConstant, Uniform, and PushConstant
  *     Storage Classes must be explicitly laid out. The following apply to all
diff --git a/src/compiler/glsl/gl_nir_link_uniforms.c b/src/compiler/glsl/gl_nir_link_uniforms.c
index 375340026a0..512dc868e73 100644
--- a/src/compiler/glsl/gl_nir_link_uniforms.c
+++ b/src/compiler/glsl/gl_nir_link_uniforms.c
@@ -28,12 +28,9 @@
 #include "main/context.h"
 #include "main/mtypes.h"
 
-/* This file do the common link for GLSL uniforms, using NIR, instead of IR as
+/**
+ * This file do the common link for GLSL uniforms, using NIR, instead of IR as
  * the counter-part glsl/link_uniforms.cpp
- *
- * Also note that this is tailored for ARB_gl_spirv needs and particularities
- * (like need to work/link without name available, explicit location for
- * normal uniforms as mandatory, and so on).
  */
 
 #define UNMAPPED_UNIFORM_LOC ~0u
diff --git a/src/compiler/glsl/gl_nir_link_xfb.c b/src/compiler/glsl/gl_nir_link_xfb.c
index 5b80a3e0373..69d11559f58 100644
--- a/src/compiler/glsl/gl_nir_link_xfb.c
+++ b/src/compiler/glsl/gl_nir_link_xfb.c
@@ -28,11 +28,8 @@
 #include "main/context.h"
 #include "util/u_math.h"
 
-/*
+/**
  * This file does the linking of GLSL transform feedback using NIR.
- *
- * Note: This linking pass is currently tailored for ARB_gl_spirv needs and
- * particularities.
  */
 
 void
diff --git a/src/compiler/glsl/gl_nir_linker.c b/src/compiler/glsl/gl_nir_linker.c
index 2ca25bda818..c8cb6457f96 100644
--- a/src/compiler/glsl/gl_nir_linker.c
+++ b/src/compiler/glsl/gl_nir_linker.c
@@ -29,10 +29,9 @@
 #include "main/shaderobj.h"
 #include "ir_uniform.h" /* for gl_uniform_storage */
 
-/* This file included general link methods, using NIR, instead of IR as
+/**
+ * This file included general link methods, using NIR, instead of IR as
  * the counter-part glsl/linker.cpp
- *
- * Also note that this is tailored for ARB_gl_spirv needs and particularities
  */
 
 /**