compiler/types: Move comments and reorganize declarations
authorCaio Oliveira <caio.oliveira@intel.com>
Fri, 8 Sep 2023 21:55:58 +0000 (14:55 -0700)
committerMarge Bot <emma+marge@anholt.net>
Wed, 25 Oct 2023 01:51:12 +0000 (01:51 +0000)
Move comments from C++ member functions to the C functions.  In
some cases just delete comments or consolidate them together.

Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25129>

src/compiler/glsl_types.h

index 4f717df..e41d013 100644 (file)
@@ -405,59 +405,19 @@ struct glsl_type {
    static const glsl_type *u8vec(unsigned components);
    /**@}*/
 
-   /**
-    * For numeric and boolean derived types returns the basic scalar type
-    *
-    * If the type is a numeric or boolean scalar, vector, or matrix type,
-    * this function gets the scalar type of the individual components.  For
-    * all other types, including arrays of numeric or boolean types, the
-    * error type is returned.
-    */
    const glsl_type *get_base_type() const;
-
-   /**
-    * Get the basic scalar type which this type aggregates.
-    *
-    * If the type is a numeric or boolean scalar, vector, or matrix, or an
-    * array of any of those, this function gets the scalar type of the
-    * individual components.  For structs and arrays of structs, this function
-    * returns the struct type.  For samplers and arrays of samplers, this
-    * function returns the sampler type.
-    */
    const glsl_type *get_scalar_type() const;
-
-   /**
-    * Gets the "bare" type without any decorations or layout information.
-    */
    const glsl_type *get_bare_type() const;
-
-   /**
-    * Gets the float16 version of this type.
-    */
    const glsl_type *get_float16_type() const;
-
-   /**
-    * Gets the int16 version of this type.
-    */
    const glsl_type *get_int16_type() const;
-
-   /**
-    * Gets the uint16 version of this type.
-    */
    const glsl_type *get_uint16_type() const;
 
-   /**
-    * Get the instance of a built-in scalar, vector, or matrix type
-    */
    static const glsl_type *get_instance(unsigned base_type, unsigned rows,
                                         unsigned columns,
                                         unsigned explicit_stride = 0,
                                         bool row_major = false,
                                         unsigned explicit_alignment = 0);
 
-   /**
-    * Get the instance of a sampler type
-    */
    static const glsl_type *get_sampler_instance(enum glsl_sampler_dim dim,
                                                 bool shadow,
                                                 bool array,
@@ -470,551 +430,135 @@ struct glsl_type {
    static const glsl_type *get_image_instance(enum glsl_sampler_dim dim,
                                               bool array, glsl_base_type type);
 
-   /**
-    * Get the instance of an array type
-    */
    static const glsl_type *get_array_instance(const glsl_type *element,
                                               unsigned array_size,
                                               unsigned explicit_stride = 0);
 
-   /**
-    * Get the instance of a cooperative matrix type
-    */
    static const glsl_type *get_cmat_instance(const struct glsl_cmat_description desc);
 
-   /**
-    * Get the instance of a record type
-    */
    static const glsl_type *get_struct_instance(const glsl_struct_field *fields,
                                               unsigned num_fields,
                                               const char *name,
                                               bool packed = false,
                                               unsigned explicit_alignment = 0);
 
-   /**
-    * Get the instance of an interface block type
-    */
    static const glsl_type *get_interface_instance(const glsl_struct_field *fields,
                                                  unsigned num_fields,
                                                  enum glsl_interface_packing packing,
                                                  bool row_major,
                                                  const char *block_name);
 
-   /**
-    * Get the instance of an subroutine type
-    */
    static const glsl_type *get_subroutine_instance(const char *subroutine_name);
 
-   /**
-    * Get the type resulting from a multiplication of \p type_a * \p type_b
-    */
    static const glsl_type *get_mul_type(const glsl_type *type_a,
                                         const glsl_type *type_b);
 
-   /**
-    * Query the total number of scalars that make up a scalar, vector or matrix
-    */
    unsigned components() const;
-
-   /**
-    * Calculate the number of components slots required to hold this type
-    *
-    * This is used to determine how many uniform or varying locations a type
-    * might occupy.
-    */
    unsigned component_slots() const;
-
    unsigned component_slots_aligned(unsigned offset) const;
-
-   /**
-    * Calculate offset between the base location of the struct in
-    * uniform storage and a struct member.
-    * For the initial call, length is the index of the member to find the
-    * offset for.
-    */
    unsigned struct_location_offset(unsigned length) const;
-
-   /**
-    * Calculate the number of unique values from glGetUniformLocation for the
-    * elements of the type.
-    *
-    * This is used to allocate slots in the UniformRemapTable, the amount of
-    * locations may not match with actual used storage space by the driver.
-    */
    unsigned uniform_locations() const;
-
-   /**
-    * Used to count the number of varyings contained in the type ignoring
-    * innermost array elements.
-    */
    unsigned varying_count() const;
-
-   /**
-    * Calculate the number of vec4 slots required to hold this type.
-    *
-    * This is the underlying recursive type_size function for
-    * count_attribute_slots() (vertex inputs and varyings) but also for
-    * gallium's !PIPE_CAP_PACKED_UNIFORMS case.
-    */
    unsigned count_vec4_slots(bool is_gl_vertex_input, bool bindless) const;
-
-   /**
-    * Calculate the number of vec4 slots required to hold this type.
-    *
-    * This is the underlying recursive type_size function for
-    * gallium's PIPE_CAP_PACKED_UNIFORMS case.
-    */
    unsigned count_dword_slots(bool bindless) const;
-
-   /**
-    * Calculate the number of attribute slots required to hold this type
-    *
-    * This implements the language rules of GLSL 1.50 for counting the number
-    * of slots used by a vertex attribute.  It also determines the number of
-    * varying slots the type will use up in the absence of varying packing
-    * (and thus, it can be used to measure the number of varying slots used by
-    * the varyings that are generated by lower_packed_varyings).
-    *
-    * For vertex shader attributes - doubles only take one slot.
-    * For inter-shader varyings - dvec3/dvec4 take two slots.
-    *
-    * Vulkan doesn’t make this distinction so the argument should always be
-    * false.
-    */
    unsigned count_attribute_slots(bool is_gl_vertex_input) const;
-
-   /**
-    * Alignment in bytes of the start of this type in a std140 uniform
-    * block.
-    */
    unsigned std140_base_alignment(bool row_major) const;
-
-   /** Size in bytes of this type in a std140 uniform block.
-    *
-    * Note that this is not GL_UNIFORM_SIZE (which is the number of
-    * elements in the array)
-    */
    unsigned std140_size(bool row_major) const;
-
-   /**
-    * Gets an explicitly laid out type with the std140 layout.
-    */
-   const glsl_type *get_explicit_std140_type(bool row_major) const;
-
-   /**
-    * Alignment in bytes of the start of this type in a std430 shader
-    * storage block.
-    */
    unsigned std430_base_alignment(bool row_major) const;
-
-   /**
-    * Calculate array stride in bytes of this type in a std430 shader storage
-    * block.
-    */
    unsigned std430_array_stride(bool row_major) const;
-
-   /**
-    * Size in bytes of this type in a std430 shader storage block.
-    *
-    * Note that this is not GL_BUFFER_SIZE
-    */
    unsigned std430_size(bool row_major) const;
+   unsigned cl_alignment() const;
+   unsigned cl_size() const;
+   unsigned explicit_size(bool align_to_stride=false) const;
+   unsigned arrays_of_arrays_size() const;
+   unsigned bit_size() const;
+   unsigned atomic_size() const;
 
-   /**
-    * Gets an explicitly laid out type with the std430 layout.
-    */
-   const glsl_type *get_explicit_std430_type(bool row_major) const;
+   int field_index(const char *name) const;
+   int array_size() const;
+   int coordinate_components() const;
 
-   /**
-    * Gets an explicitly laid out interface type.
-    */
+   const glsl_type *replace_vec3_with_vec4() const;
+   const glsl_type *get_explicit_std140_type(bool row_major) const;
+   const glsl_type *get_explicit_std430_type(bool row_major) const;
    const glsl_type *get_explicit_interface_type(bool supports_std430) const;
-
-   /** Returns an explicitly laid out type given a type and size/align func
-    *
-    * The size/align func is only called for scalar and vector types and the
-    * returned type is otherwise laid out in the natural way as follows:
-    *
-    *  - Arrays and matrices have a stride of ALIGN(elem_size, elem_align).
-    *
-    *  - Structure types have their elements in-order and as tightly packed as
-    *    possible following the alignment required by the size/align func.
-    *
-    *  - All composite types (structures, matrices, and arrays) have an
-    *    alignment equal to the highest alignment of any member of the composite.
-    *
-    * The types returned by this function are likely not suitable for most UBO
-    * or SSBO layout because they do not add the extra array and substructure
-    * alignment that is required by std140 and std430.
-    */
    const glsl_type *get_explicit_type_for_size_align(glsl_type_size_align_func type_info,
                                                      unsigned *size, unsigned *align) const;
+   const glsl_type *without_array() const;
+   const glsl_type *row_type() const;
+   const glsl_type *column_type() const;
 
-   const glsl_type *replace_vec3_with_vec4() const;
-
-   /**
-    * Alignment in bytes of the start of this type in OpenCL memory.
-    */
-   unsigned cl_alignment() const;
-
-   /**
-    * Size in bytes of this type in OpenCL memory
-    */
-   unsigned cl_size() const;
-
-   /**
-    * Size in bytes of this type based on its explicit data.
-    *
-    * When using SPIR-V shaders (ARB_gl_spirv), memory layouts are expressed
-    * through explicit offset, stride and matrix layout, so the size
-    * can/should be computed used those values.
-    *
-    * Note that the value returned by this method is only correct if such
-    * values are set, so only with SPIR-V shaders. Should not be used with
-    * GLSL shaders.
-    */
-   unsigned explicit_size(bool align_to_stride=false) const;
-
-   /**
-    * Query whether or not a type is a scalar (non-vector and non-matrix).
-    */
    bool is_scalar() const;
-
-   /**
-    * Query whether or not a type is a vector
-    */
    bool is_vector() const;
-
-   /**
-    * Query whether or not a type is a matrix
-    */
    bool is_matrix() const;
-
-   /**
-    * Query whether or not a type is a non-array numeric type
-    */
    bool is_numeric() const;
-
-   /**
-    * Query whether or not a type is an integer.
-    */
    bool is_integer() const;
-
-   /**
-    * Query whether or not a type is a 16-bit integer.
-    */
    bool is_integer_16() const;
-
-   /**
-    * Query whether or not a type is an 32-bit integer.
-    */
    bool is_integer_32() const;
-
-   /**
-    * Query whether or not a type is a 64-bit integer.
-    */
    bool is_integer_64() const;
-
-   /**
-    * Query whether or not a type is a 32-bit or 64-bit integer
-    */
    bool is_integer_32_64() const;
-
-   /**
-    * Query whether or not a type is a 16-bit or 32-bit integer
-    */
    bool is_integer_16_32() const;
-
-   /**
-    * Query whether or not a type is a 16-bit, 32-bit or 64-bit integer
-    */
    bool is_integer_16_32_64() const;
-
-   /**
-    * Query whether or not type is an integral type, or for struct and array
-    * types, contains an integral type.
-    */
-   bool contains_integer() const;
-
-   /**
-    * Query whether or not type is a double type, or for struct, interface and
-    * array types, contains a double type.
-    */
-   bool contains_double() const;
-
-   /**
-    * Query whether or not type is a 64-bit type, or for struct, interface and
-    * array types, contains a double type.
-    */
-   bool contains_64bit() const;
-
-   /**
-    * Query whether or not a type is a float type
-    */
    bool is_float() const;
-
-   /**
-    * Query whether or not a type is a half-float or float type
-    */
    bool is_float_16_32() const;
-
-   /**
-    * Query whether or not a type is a half-float, float or double
-    */
    bool is_float_16_32_64() const;
-
-   /**
-    * Query whether or not a type is a float or double
-    */
    bool is_float_32_64() const;
-
    bool is_int_16_32_64() const;
-
    bool is_uint_16_32_64() const;
-
    bool is_int_16_32() const;
-
    bool is_uint_16_32() const;
-
-   /**
-    * Query whether or not a type is a double type
-    */
    bool is_double() const;
-
-   /**
-    * Query whether a 64-bit type takes two slots.
-    */
    bool is_dual_slot() const;
-
-   /**
-    * Query whether or not a type is 64-bit
-    */
    bool is_64bit() const;
-
-   /**
-    * Query whether or not a type is 16-bit
-    */
    bool is_16bit() const;
-
-   /**
-    * Query whether or not a type is 32-bit
-    */
    bool is_32bit() const;
-
-   /**
-    * Query whether or not a type is a non-array boolean type
-    */
    bool is_boolean() const;
-
-   /**
-    * Query whether or not a type is a sampler
-    */
    bool is_sampler() const;
-
-   /**
-    * Query whether or not a type is a texture
-    */
    bool is_texture() const;
-
-   /**
-    * Query whether or not type is a sampler, or for struct, interface and
-    * array types, contains a sampler.
-    */
-   bool contains_sampler() const;
-
-   /**
-    * Query whether or not type is an array or for struct, interface and
-    * array types, contains an array.
-    */
-   bool contains_array() const;
-
-   /**
-    * Query whether or not type is an image, or for struct, interface and
-    * array types, contains an image.
-    */
-   bool contains_image() const;
-
-   /**
-    * Query whether or not a type is an image
-    */
    bool is_image() const;
-
-   /**
-    * Query whether or not a type is an array
-    */
    bool is_array() const;
-
    bool is_array_of_arrays() const;
-
    bool is_cmat() const;
-
-   /**
-    * Query whether or not a type is a record
-    */
    bool is_struct() const;
-
-   /**
-    * Query whether or not a type is an interface
-    */
    bool is_interface() const;
-
-   /**
-    * Query whether or not a type is the void type singleton.
-    */
    bool is_void() const;
-
-   /**
-    * Query whether or not a type is the error type singleton.
-    */
    bool is_error() const;
-
-   /**
-    * Query if a type is unnamed/anonymous (named by the parser)
-    */
-
    bool is_subroutine() const;
-   bool contains_subroutine() const;
-   bool is_anonymous() const;
-
-   /**
-    * Get the type stripped of any arrays
-    *
-    * \return
-    * Pointer to the type of elements of the first non-array type for array
-    * types, or pointer to itself for non-array types.
-    */
-   const glsl_type *without_array() const;
-
-   /**
-    * Return the total number of elements in an array including the elements
-    * in arrays of arrays.
-    */
-   unsigned arrays_of_arrays_size() const;
-
-   /**
-    * Return bit size for this type.
-    */
-   unsigned bit_size() const;
-
-
-   /**
-    * Query whether or not a type is an atomic_uint.
-    */
    bool is_atomic_uint() const;
+   bool is_unsized_array() const;
 
-   /**
-    * Return the amount of atomic counter storage required for a type.
-    */
-   unsigned atomic_size() const;
-
-   /**
-    * Return whether a type contains any atomic counters.
-    */
+   bool contains_integer() const;
+   bool contains_double() const;
+   bool contains_64bit() const;
+   bool contains_sampler() const;
+   bool contains_array() const;
+   bool contains_image() const;
+   bool contains_subroutine() const;
    bool contains_atomic() const;
-
-   /**
-    * Return whether a type contains any opaque types.
-    */
    bool contains_opaque() const;
 
-   /**
-    * Query the full type of a matrix row
-    *
-    * \return
-    * If the type is not a matrix, \c glsl_type::error_type is returned.
-    * Otherwise a type matching the rows of the matrix is returned.
-    */
-   const glsl_type *row_type() const;
-
-   /**
-    * Query the full type of a matrix column
-    *
-    * \return
-    * If the type is not a matrix, \c glsl_type::error_type is returned.
-    * Otherwise a type matching the columns of the matrix is returned.
-    */
-   const glsl_type *column_type() const;
-
-   /**
-    * Get the type of a structure field
-    *
-    * \return
-    * Pointer to the type of the named field.  If the type is not a structure
-    * or the named field does not exist, \c glsl_type::error_type is returned.
-    */
-   const glsl_type *field_type(const char *name) const;
-
-   /**
-    * Get the location of a field within a record type
-    */
-   int field_index(const char *name) const;
-
-   /**
-    * Query the number of elements in an array type
-    *
-    * \return
-    * The number of elements in the array for array types or -1 for non-array
-    * types.  If the number of elements in the array has not yet been declared,
-    * zero is returned.
-    */
-   int array_size() const;
-
-   /**
-    * Query whether the array size for all dimensions has been declared.
-    */
-   bool is_unsized_array() const;
-
-   /**
-    * Return the number of coordinate components needed for this
-    * sampler or image type.
-    *
-    * This is based purely on the sampler's dimensionality.  For example, this
-    * returns 1 for sampler1D, and 3 for sampler2DArray.
-    *
-    * Note that this is often different than actual coordinate type used in
-    * a texturing built-in function, since those pack additional values (such
-    * as the shadow comparator or projector) into the coordinate type.
-    */
-   int coordinate_components() const;
-
-   /**
-    * Compares whether this type matches another type without taking into
-    * account the precision in structures.
-    *
-    * This is applied recursively so that structures containing structure
-    * members can also ignore the precision.
-    */
    bool compare_no_precision(const glsl_type *b) const;
-
-   /**
-    * Compare a record type against another record type.
-    *
-    * This is useful for matching record types declared on the same shader
-    * stage as well as across different shader stages.
-    * The option to not match name is needed for matching record types
-    * declared across different shader stages.
-    * The option to not match locations is to deal with places where the
-    * same struct is defined in a block which has a location set on it.
-    */
    bool record_compare(const glsl_type *b, bool match_name,
                        bool match_locations = true,
                        bool match_precision = true) const;
 
-   /**
-    * Get the type interface packing.
-    */
    enum glsl_interface_packing get_interface_packing() const;
+   enum glsl_interface_packing get_internal_ifc_packing(bool std430_supported) const;
+   bool get_interface_row_major() const;
 
    /**
-    * Get the type interface packing used internally. For shared and packing
-    * layouts this is implementation defined.
+    * Query if a type is unnamed/anonymous (named by the parser)
     */
-   enum glsl_interface_packing get_internal_ifc_packing(bool std430_supported) const;
+   bool is_anonymous() const;
 
    /**
-    * Check if the type interface is row major
+    * Get the type of a structure field
+    *
+    * \return
+    * Pointer to the type of the named field.  If the type is not a structure
+    * or the named field does not exist, \c glsl_type::error_type is returned.
     */
-   bool get_interface_row_major() const;
+   const glsl_type *field_type(const char *name) const;
 
 #endif /* __cplusplus */
 };
@@ -1243,7 +787,12 @@ bool glsl_type_is_scalar(const struct glsl_type *t);
 bool glsl_type_is_vector_or_scalar(const struct glsl_type *t);
 bool glsl_type_is_matrix(const struct glsl_type *t);
 bool glsl_type_is_array_or_matrix(const struct glsl_type *t);
+
+/**
+ * Query whether a 64-bit type takes two slots.
+ */
 bool glsl_type_is_dual_slot(const struct glsl_type *t);
+
 bool glsl_type_is_leaf(const struct glsl_type *type);
 
 static inline bool
@@ -1276,8 +825,30 @@ glsl_struct_type_is_packed(const struct glsl_type *t)
    return t->packed;
 }
 
+/**
+ * Gets the "bare" type without any decorations or layout information.
+ */
 const struct glsl_type *glsl_get_bare_type(const struct glsl_type *t);
+
+/**
+ * Get the basic scalar type which this type aggregates.
+ *
+ * If the type is a numeric or boolean scalar, vector, or matrix, or an
+ * array of any of those, this function gets the scalar type of the
+ * individual components.  For structs and arrays of structs, this function
+ * returns the struct type.  For samplers and arrays of samplers, this
+ * function returns the sampler type.
+ */
 const struct glsl_type *glsl_get_scalar_type(const struct glsl_type *t);
+
+/**
+ * For numeric and boolean derived types returns the basic scalar type
+ *
+ * If the type is a numeric or boolean scalar, vector, or matrix type,
+ * this function gets the scalar type of the individual components.  For
+ * all other types, including arrays of numeric or boolean types, the
+ * error type is returned.
+ */
 const struct glsl_type *glsl_get_base_glsl_type(const struct glsl_type *t);
 
 unsigned glsl_get_length(const struct glsl_type *t);
@@ -1288,6 +859,9 @@ glsl_get_vector_elements(const struct glsl_type *t)
    return t->vector_elements;
 }
 
+/**
+ * Query the total number of scalars that make up a scalar, vector or matrix
+ */
 static inline unsigned
 glsl_get_components(const struct glsl_type *t)
 {
@@ -1302,15 +876,38 @@ glsl_get_matrix_columns(const struct glsl_type *t)
 
 const struct glsl_type *glsl_type_wrap_in_arrays(const struct glsl_type *t,
                                                  const struct glsl_type *arrays);
+
+/**
+ * Query the number of elements in an array type
+ *
+ * \return
+ * The number of elements in the array for array types or -1 for non-array
+ * types.  If the number of elements in the array has not yet been declared,
+ * zero is returned.
+ */
 static inline int
 glsl_array_size(const struct glsl_type *t)
 {
    return glsl_type_is_array(t) ? t->length : -1;
 }
 
+/**
+ * Return the total number of elements in an array including the elements
+ * in arrays of arrays.
+ */
 unsigned glsl_get_aoa_size(const struct glsl_type *t);
+
 const struct glsl_type *glsl_get_array_element(const struct glsl_type *t);
+
+/**
+ * Get the type stripped of any arrays
+ *
+ * \return
+ * Pointer to the type of elements of the first non-array type for array
+ * types, or pointer to itself for non-array types.
+ */
 const struct glsl_type *glsl_without_array(const struct glsl_type *t);
+
 const struct glsl_type *glsl_without_array_or_matrix(const struct glsl_type *t);
 const struct glsl_type *glsl_type_wrap_in_arrays(const struct glsl_type *t,
                                                  const struct glsl_type *arrays);
@@ -1318,8 +915,15 @@ const struct glsl_type *glsl_type_wrap_in_arrays(const struct glsl_type *t,
 const struct glsl_type *glsl_get_cmat_element(const struct glsl_type *t);
 const struct glsl_cmat_description *glsl_get_cmat_description(const struct glsl_type *t);
 
+/**
+ * Return the amount of atomic counter storage required for a type.
+ */
 unsigned glsl_atomic_size(const struct glsl_type *type);
 
+/**
+ * Type A contains type B if A is B or A is a composite type (struct,
+ * interface, array) that has an element that contains B.
+ */
 bool glsl_type_contains_64bit(const struct glsl_type *t);
 bool glsl_type_contains_image(const struct glsl_type *t);
 bool glsl_contains_atomic(const struct glsl_type *t);
@@ -1348,16 +952,56 @@ glsl_get_sampler_result_type(const struct glsl_type *t)
    return (enum glsl_base_type)t->sampled_type;
 }
 
+/**
+ * Return the number of coordinate components needed for this
+ * sampler or image type.
+ *
+ * This is based purely on the sampler's dimensionality.  For example, this
+ * returns 1 for sampler1D, and 3 for sampler2DArray.
+ *
+ * Note that this is often different than actual coordinate type used in
+ * a texturing built-in function, since those pack additional values (such
+ * as the shadow comparator or projector) into the coordinate type.
+ */
 int glsl_get_sampler_coordinate_components(const struct glsl_type *t);
 
+/**
+ * Compares whether this type matches another type without taking into
+ * account the precision in structures.
+ *
+ * This is applied recursively so that structures containing structure
+ * members can also ignore the precision.
+ */
 bool glsl_type_compare_no_precision(const struct glsl_type *a, const struct glsl_type *b);
+
+/**
+ * Compare a record type against another record type.
+ *
+ * This is useful for matching record types declared on the same shader
+ * stage as well as across different shader stages.
+ * The option to not match name is needed for matching record types
+ * declared across different shader stages.
+ * The option to not match locations is to deal with places where the
+ * same struct is defined in a block which has a location set on it.
+ */
 bool glsl_record_compare(const struct glsl_type *a, const struct glsl_type *b,
                          bool match_name, bool match_locations,
                          bool match_precision);
 
 const struct glsl_type *glsl_get_struct_field(const struct glsl_type *t, unsigned index);
 const struct glsl_struct_field *glsl_get_struct_field_data(const struct glsl_type *t, unsigned index);
+
+/**
+ * Calculate offset between the base location of the struct in
+ * uniform storage and a struct member.
+ * For the initial call, length is the index of the member to find the
+ * offset for.
+ */
 unsigned glsl_get_struct_location_offset(const struct glsl_type *t, unsigned length);
+
+/**
+ * Get the location of a field within a record type
+ */
 int glsl_get_field_index(const struct glsl_type *t, const char *name);
 
 static inline int
@@ -1488,16 +1132,62 @@ const struct glsl_type *glsl_interface_type(const struct glsl_struct_field *fiel
                                             const char *block_name);
 const struct glsl_type *glsl_subroutine_type(const char *subroutine_name);
 
+/**
+ * Query the full type of a matrix row
+ *
+ * \return
+ * If the type is not a matrix, \c glsl_type::error_type is returned.
+ * Otherwise a type matching the rows of the matrix is returned.
+ */
 const struct glsl_type *glsl_get_row_type(const struct glsl_type *t);
+
+/**
+ * Query the full type of a matrix column
+ *
+ * \return
+ * If the type is not a matrix, \c glsl_type::error_type is returned.
+ * Otherwise a type matching the columns of the matrix is returned.
+ */
 const struct glsl_type *glsl_get_column_type(const struct glsl_type *t);
+
+/** Returns an explicitly laid out type given a type and size/align func
+ *
+ * The size/align func is only called for scalar and vector types and the
+ * returned type is otherwise laid out in the natural way as follows:
+ *
+ *  - Arrays and matrices have a stride of ALIGN(elem_size, elem_align).
+ *
+ *  - Structure types have their elements in-order and as tightly packed as
+ *    possible following the alignment required by the size/align func.
+ *
+ *  - All composite types (structures, matrices, and arrays) have an
+ *    alignment equal to the highest alignment of any member of the composite.
+ *
+ * The types returned by this function are likely not suitable for most UBO
+ * or SSBO layout because they do not add the extra array and substructure
+ * alignment that is required by std140 and std430.
+ */
 const struct glsl_type *glsl_get_explicit_type_for_size_align(const struct glsl_type *type,
                                                               glsl_type_size_align_func type_info,
                                                               unsigned *size, unsigned *align);
+
 const struct glsl_type *glsl_type_replace_vec3_with_vec4(const struct glsl_type *type);
 
+/**
+ * Gets the float16 version of this type.
+ */
 const struct glsl_type *glsl_float16_type(const struct glsl_type *t);
+
+/**
+ * Gets the int16 version of this type.
+ */
 const struct glsl_type *glsl_int16_type(const struct glsl_type *t);
+
+/**
+ * Gets the uint16 version of this type.
+ */
 const struct glsl_type *glsl_uint16_type(const struct glsl_type *t);
+
 const struct glsl_type *glsl_type_to_16bit(const struct glsl_type *old_type);
 
 static inline const struct glsl_type *
@@ -1563,30 +1253,96 @@ glsl_sampler_type_to_texture(const struct glsl_type *t)
 
 const struct glsl_type *glsl_replace_vector_type(const struct glsl_type *t, unsigned components);
 const struct glsl_type *glsl_channel_type(const struct glsl_type *t);
+
+/**
+ * Get the type resulting from a multiplication of \p type_a * \p type_b
+ */
 const struct glsl_type *glsl_get_mul_type(const struct glsl_type *type_a, const struct glsl_type *type_b);
 
 unsigned glsl_type_get_sampler_count(const struct glsl_type *t);
 unsigned glsl_type_get_texture_count(const struct glsl_type *t);
 unsigned glsl_type_get_image_count(const struct glsl_type *t);
 
+/**
+ * Calculate the number of vec4 slots required to hold this type.
+ *
+ * This is the underlying recursive type_size function for
+ * count_attribute_slots() (vertex inputs and varyings) but also for
+ * gallium's !PIPE_CAP_PACKED_UNIFORMS case.
+ */
 unsigned glsl_count_vec4_slots(const struct glsl_type *t, bool is_gl_vertex_input, bool is_bindless);
+
+/**
+ * Calculate the number of vec4 slots required to hold this type.
+ *
+ * This is the underlying recursive type_size function for
+ * gallium's PIPE_CAP_PACKED_UNIFORMS case.
+ */
 unsigned glsl_count_dword_slots(const struct glsl_type *t, bool is_bindless);
+
+/**
+ * Calculate the number of components slots required to hold this type
+ *
+ * This is used to determine how many uniform or varying locations a type
+ * might occupy.
+ */
 unsigned glsl_get_component_slots(const struct glsl_type *t);
+
 unsigned glsl_get_component_slots_aligned(const struct glsl_type *t, unsigned offset);
+
+/**
+ * Used to count the number of varyings contained in the type ignoring
+ * innermost array elements.
+ */
 unsigned glsl_varying_count(const struct glsl_type *t);
+
+/**
+ * Calculate the number of unique values from glGetUniformLocation for the
+ * elements of the type.
+ *
+ * This is used to allocate slots in the UniformRemapTable, the amount of
+ * locations may not match with actual used storage space by the driver.
+ */
 unsigned glsl_type_uniform_locations(const struct glsl_type *t);
 
+/**
+ * Calculate the number of attribute slots required to hold this type
+ *
+ * This implements the language rules of GLSL 1.50 for counting the number
+ * of slots used by a vertex attribute.  It also determines the number of
+ * varying slots the type will use up in the absence of varying packing
+ * (and thus, it can be used to measure the number of varying slots used by
+ * the varyings that are generated by lower_packed_varyings).
+ *
+ * For vertex shader attributes - doubles only take one slot.
+ * For inter-shader varyings - dvec3/dvec4 take two slots.
+ *
+ * Vulkan doesn’t make this distinction so the argument should always be
+ * false.
+ */
 static inline unsigned
 glsl_count_attribute_slots(const struct glsl_type *t, bool is_gl_vertex_input)
 {
    return glsl_count_vec4_slots(t, is_gl_vertex_input, true);
 }
 
+/**
+ * Size in bytes of this type in OpenCL memory
+ */
 unsigned glsl_get_cl_size(const struct glsl_type *t);
+
+/**
+ * Alignment in bytes of the start of this type in OpenCL memory.
+ */
 unsigned glsl_get_cl_alignment(const struct glsl_type *t);
+
 void glsl_get_cl_type_size_align(const struct glsl_type *t,
                                  unsigned *size, unsigned *align);
 
+/**
+ * Get the type interface packing used internally. For shared and packing
+ * layouts this is implementation defined.
+ */
 enum glsl_interface_packing glsl_get_internal_ifc_packing(const struct glsl_type *t, bool std430_supported);
 
 static inline enum glsl_interface_packing
@@ -1595,11 +1351,49 @@ glsl_get_ifc_packing(const struct glsl_type *t)
    return (enum glsl_interface_packing)t->interface_packing;
 }
 
+/**
+ * Alignment in bytes of the start of this type in a std140 uniform
+ * block.
+ */
 unsigned glsl_get_std140_base_alignment(const struct glsl_type *t, bool row_major);
+
+/** Size in bytes of this type in a std140 uniform block.
+ *
+ * Note that this is not GL_UNIFORM_SIZE (which is the number of
+ * elements in the array)
+ */
 unsigned glsl_get_std140_size(const struct glsl_type *t, bool row_major);
+
+/**
+ * Calculate array stride in bytes of this type in a std430 shader storage
+ * block.
+ */
 unsigned glsl_get_std430_array_stride(const struct glsl_type *t, bool row_major);
+
+/**
+ * Alignment in bytes of the start of this type in a std430 shader
+ * storage block.
+ */
 unsigned glsl_get_std430_base_alignment(const struct glsl_type *t, bool row_major);
+
+/**
+ * Size in bytes of this type in a std430 shader storage block.
+ *
+ * Note that this is not GL_BUFFER_SIZE
+ */
 unsigned glsl_get_std430_size(const struct glsl_type *t, bool row_major);
+
+/**
+ * Size in bytes of this type based on its explicit data.
+ *
+ * When using SPIR-V shaders (ARB_gl_spirv), memory layouts are expressed
+ * through explicit offset, stride and matrix layout, so the size
+ * can/should be computed used those values.
+ *
+ * Note that the value returned by this method is only correct if such
+ * values are set, so only with SPIR-V shaders. Should not be used with
+ * GLSL shaders.
+ */
 unsigned glsl_get_explicit_size(const struct glsl_type *t, bool align_to_stride);
 
 static inline unsigned
@@ -1614,9 +1408,19 @@ glsl_get_explicit_alignment(const struct glsl_type *t)
    return t->explicit_alignment;
 }
 
+/**
+ * Gets an explicitly laid out type with the std140 layout.
+ */
 const struct glsl_type *glsl_get_explicit_std140_type(const struct glsl_type *t, bool row_major);
+
+/**
+ * Gets an explicitly laid out type with the std430 layout.
+ */
 const struct glsl_type *glsl_get_explicit_std430_type(const struct glsl_type *t, bool row_major);
 
+/**
+ * Gets an explicitly laid out interface type.
+ */
 static inline const struct glsl_type *
 glsl_get_explicit_interface_type(const struct glsl_type *t, bool supports_std430)
 {