docs/nir: use hawkmoth instead of doxygen

Use the hawkmoth c:auto* directives to incorporate nir documentation.

Convert @param style parameter descriptions to rst info field lists.
Add static stubs for generated headers. Fix a lot of references, in
particular the symbols are now in the Sphinx C domain, not C++
domain. Tweak syntax here and there.

Based on the earlier work by Erik Faye-Lund <kusmabite@gmail.com>

Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>

docs/conf.py

@@ -224,6 +224,7 @@ hawkmoth_clang = [
   '-Idocs/header-stubs/',
   '-Iinclude/',
   '-Isrc/',
+  '-Isrc/gallium/include/',
   '-DHAVE_STRUCT_TIMESPEC',
   '-DHAVE_PTHREAD',
   '-DHAVE_ENDIAN_H',

docs/header-stubs/nir_intrinsics.h

@@ -0,0 +1,2 @@
+typedef enum { nir_num_intrinsics = 0 } nir_intrinsic_op;
+typedef enum { NIR_INTRINSIC_NUM_INDEX_FLAGS } nir_intrinsic_index_flag;

docs/header-stubs/nir_opcodes.h

@@ -0,0 +1 @@
+typedef enum { nir_num_opcodes = 0 } nir_op;

docs/nir/alu.rst

@@ -9,13 +9,13 @@ identical output.  A good rule of thumb is that only things which can be
 constant folded should be ALU operations.  If it can't be constant folded, then
 it should probably be an intrinsic instead.
 
-Each ALU instruction has an opcode, which is a member of the :cpp:enum:`nir_op`
+Each ALU instruction has an opcode, which is a member of the :c:enum:`nir_op`
 enum, that describes what it does as well as how many arguments it takes.
 Associated with each opcode is an metadata structure,
-:cpp:struct:`nir_op_info`, which shows how many arguments the opcode takes,
+:c:struct:`nir_op_info`, which shows how many arguments the opcode takes,
 information about data types, and algebraic properties such as associativity
 and commutativity. The info structure for each opcode may be accessed through
-a global :cpp:var:`nir_op_infos` array that’s indexed by the opcode.
+a global :c:var:`nir_op_infos` array that’s indexed by the opcode.
 
 ALU operations are typeless, meaning that they're only defined to convert
 a certain bit-pattern input to another bit-pattern output.  The only concrete
@@ -48,21 +48,22 @@ components required by each source which is fixed by the opcode.
 
 While most instruction types in NIR require vector sizes to perfectly match on
 inputs and outputs, ALU instruction sources have an additional
-:cpp:member:`nir_alu_src::swizzle` field which allows them to act on vectors
+:c:member:`nir_alu_src.swizzle` field which allows them to act on vectors
 which are not the native vector size of the instruction.  This is ideal for
 hardware with a native data type of `vec4` but also means that ALU
 instructions are often used (and required) for packing/unpacking vectors for
 use in other instruction types like intrinsics or texture ops.
 
-.. doxygenstruct:: nir_op_info
+.. c:autostruct:: nir_op_info
+   :file: src/compiler/nir/nir.h
    :members:
 
-.. doxygenvariable:: nir_op_infos
+.. c:autovar:: nir_op_infos
 
-.. doxygenstruct:: nir_alu_instr
+.. c:autostruct:: nir_alu_instr
    :members:
 
-.. doxygenstruct:: nir_alu_src
+.. c:autostruct:: nir_alu_src
    :members:
 
 NIR ALU Opcode Reference:

docs/nir/tex.rst

@@ -5,14 +5,17 @@ Even though texture instructions *could* be supported as intrinsics, the vast
 number of combinations mean that doing so is practically impossible. Instead,
 NIR has a dedicated texture instruction.  There are several texture operations:
 
-.. doxygenenum:: nir_texop
+.. c:autoenum:: nir_texop
+   :file: src/compiler/nir/nir.h
+   :members:
 
 As with other instruction types, there is still an array of sources, except
 that each source also has a *type* associated with it.  There are various
 source types, each corresponding to a piece of information that the different
 texture operations require.
 
-.. doxygenenum:: nir_tex_src_type
+.. c:autoenum:: nir_tex_src_type
+   :members:
 
 Of particular interest are the texture/sampler deref/index/handle source types.
 First, note that textures and samplers are specified separately in NIR.  While
@@ -28,12 +31,12 @@ Also, like a lot of other resources, there are multiple ways to represent a
 texture in NIR. It can be referenced by a variable dereference, an index, or a
 bindless handle. When using an index or a bindless handle, the texture type
 information is generally not available.  To handle this, various information
-from the type is redundantly stored in the :cpp:struct:`nir_tex_instr` itself.
+from the type is redundantly stored in the :c:struct:`nir_tex_instr` itself.
 
-.. doxygenstruct:: nir_tex_instr
+.. c:autostruct:: nir_tex_instr
    :members:
 
-.. doxygenstruct:: nir_tex_src
+.. c:autostruct:: nir_tex_src
    :members:
 
 Texture instruction helpers
@@ -42,17 +45,27 @@ Texture instruction helpers
 There are a number of helper functions for working with NIR texture
 instructions.  They are documented here in no particular order.
 
-.. doxygenfunction:: nir_tex_instr_create
+.. c:autofunction:: nir_tex_instr_create
-.. doxygenfunction:: nir_tex_instr_need_sampler
+
-.. doxygenfunction:: nir_tex_instr_result_size
+.. c:autofunction:: nir_tex_instr_need_sampler
-.. doxygenfunction:: nir_tex_instr_dest_size
+
-.. doxygenfunction:: nir_tex_instr_is_query
+.. c:autofunction:: nir_tex_instr_result_size
-.. doxygenfunction:: nir_tex_instr_has_implicit_derivative
+
-.. doxygenfunction:: nir_tex_instr_src_type
+.. c:autofunction:: nir_tex_instr_dest_size
-.. doxygenfunction:: nir_tex_instr_src_size
+
-.. doxygenfunction:: nir_tex_instr_src_index
+.. c:autofunction:: nir_tex_instr_is_query
-.. doxygenfunction:: nir_tex_instr_add_src
+
-.. doxygenfunction:: nir_tex_instr_remove_src
+.. c:autofunction:: nir_tex_instr_has_implicit_derivative
+
+.. c:autofunction:: nir_tex_instr_src_type
+
+.. c:autofunction:: nir_tex_instr_src_size
+
+.. c:autofunction:: nir_tex_instr_src_index
+
+.. c:autofunction:: nir_tex_instr_add_src
+
+.. c:autofunction:: nir_tex_instr_remove_src
 
 Texture instruction lowering
 ----------------------------
@@ -61,7 +74,10 @@ Because most hardware only supports some subset of all possible GLSL/SPIR-V
 texture operations, NIR provides a quite powerful lowering pass which is able
 to implement more complex texture operations in terms of simpler ones.
 
-.. doxygenfunction:: nir_lower_tex
+.. c:autofunction:: nir_lower_tex
-.. doxygenstruct:: nir_lower_tex_options
+
+.. c:autostruct:: nir_lower_tex_options
+   :members:
+
+.. c:autoenum:: nir_lower_tex_packing
    :members:
-.. doxygenenum:: nir_lower_tex_packing

src/compiler/nir/nir.h

@@ -167,7 +167,7 @@ struct nir_xfb_info;
 /**
  * Description of built-in state associated with a uniform
  *
- * \sa nir_variable::state_slots
+ * :c:member:`nir_variable.state_slots`
  */
 typedef struct {
    gl_state_index16 tokens[STATE_LENGTH];
@@ -405,7 +405,7 @@ typedef struct nir_constant {
     * Value of the constant.
     *
     * The field used to back the values supplied by the constant is determined
-    * by the type associated with the \c nir_variable.  Constants may be
+    * by the type associated with the ``nir_variable``.  Constants may be
     * scalars, vectors, or matrices.
     */
    nir_const_value values[NIR_MAX_VEC_COMPONENTS];
@@ -423,7 +423,7 @@ typedef struct nir_constant {
 } nir_constant;
 
 /**
- * \brief Layout qualifiers for gl_FragDepth.
+ * Layout qualifiers for gl_FragDepth.
  *
  * The AMD/ARB_conservative_depth extensions allow gl_FragDepth to be redeclared
  * with a layout qualifier.
@@ -481,14 +481,14 @@ typedef struct nir_variable {
       /**
        * Storage class of the variable.
        *
-       * \sa nir_variable_mode
+       * :c:struct:`nir_variable_mode`
        */
       unsigned mode : 18;
 
       /**
        * Is the variable read-only?
        *
-       * This is set for variables declared as \c const, shader inputs,
+       * This is set for variables declared as ``const``, shader inputs,
        * and uniforms.
        */
       unsigned read_only : 1;
@@ -556,7 +556,7 @@ typedef struct nir_variable {
       /**
        * Interpolation mode for shader inputs / outputs
        *
-       * \sa glsl_interp_mode
+       * :c:enum:`glsl_interp_mode`
        */
       unsigned interpolation : 3;
 
@@ -565,7 +565,7 @@ typedef struct nir_variable {
        * into a single varying slot, so this offset should be applied when
        * accessing components.  For example, an offset of 1 means that the x
        * component of this variable is actually stored in component y of the
-       * location specified by \c location.
+       * location specified by ``location``.
        */
       unsigned location_frac : 2;
 
@@ -597,8 +597,8 @@ typedef struct nir_variable {
       /**
        * Was the location explicitly set in the shader?
        *
-       * If the location is explicitly set in the shader, it \b cannot be changed
+       * If the location is explicitly set in the shader, it **cannot** be changed
-       * by the linker or by the API (e.g., calls to \c glBindAttribLocation have
+       * by the linker or by the API (e.g., calls to ``glBindAttribLocation`` have
        * no effect).
        */
       unsigned explicit_location : 1;
@@ -685,10 +685,10 @@ typedef struct nir_variable {
       unsigned per_vertex : 1;
 
       /**
-       * \brief Layout qualifier for gl_FragDepth. See nir_depth_layout.
+       * Layout qualifier for gl_FragDepth. See nir_depth_layout.
        *
-       * This is not equal to \c ir_depth_layout_none if and only if this
+       * This is not equal to ``ir_depth_layout_none`` if and only if this
-       * variable is \c gl_FragDepth and a layout qualifier is specified.
+       * variable is ``gl_FragDepth`` and a layout qualifier is specified.
        */
       unsigned depth_layout : 3;
 
@@ -730,15 +730,15 @@ typedef struct nir_variable {
        *
        * The precise meaning of this field depends on the nature of the variable.
        *
-       *   - Vertex shader input: one of the values from \c gl_vert_attrib.
+       *   - Vertex shader input: one of the values from ``gl_vert_attrib``.
-       *   - Vertex shader output: one of the values from \c gl_varying_slot.
+       *   - Vertex shader output: one of the values from ``gl_varying_slot``.
-       *   - Geometry shader input: one of the values from \c gl_varying_slot.
+       *   - Geometry shader input: one of the values from ``gl_varying_slot``.
-       *   - Geometry shader output: one of the values from \c gl_varying_slot.
+       *   - Geometry shader output: one of the values from ``gl_varying_slot``.
-       *   - Fragment shader input: one of the values from \c gl_varying_slot.
+       *   - Fragment shader input: one of the values from ``gl_varying_slot``.
-       *   - Fragment shader output: one of the values from \c gl_frag_result.
+       *   - Fragment shader output: one of the values from ``gl_frag_result``.
-       *   - Task shader output: one of the values from \c gl_varying_slot.
+       *   - Task shader output: one of the values from ``gl_varying_slot``.
-       *   - Mesh shader input: one of the values from \c gl_varying_slot.
+       *   - Mesh shader input: one of the values from ``gl_varying_slot``.
-       *   - Mesh shader output: one of the values from \c gl_varying_slot.
+       *   - Mesh shader output: one of the values from ``gl_varying_slot``.
        *   - Uniforms: Per-stage uniform slot number for default uniform block.
        *   - Uniforms: Index within the uniform block definition for UBO members.
        *   - Non-UBO Uniforms: uniform slot number.
@@ -806,13 +806,13 @@ typedef struct nir_variable {
    /**
     * Built-in state that backs this uniform
     *
-    * Once set at variable creation, \c state_slots must remain invariant.
+    * Once set at variable creation, ``state_slots`` must remain invariant.
     * This is because, ideally, this array would be shared by all clones of
     * this variable in the IR tree.  In other words, we'd really like for it
     * to be a fly-weight.
     *
-    * If the variable is not a uniform, \c num_state_slots will be zero and
+    * If the variable is not a uniform, ``num_state_slots`` will be zero and
-    * \c state_slots will be \c NULL.
+    * ``state_slots`` will be ``NULL``.
     *
     * Number of state slots used.
     */
@@ -839,9 +839,9 @@ typedef struct nir_variable {
 
    /**
     * For variables that are in an interface block or are an instance of an
-    * interface block, this is the \c GLSL_TYPE_INTERFACE type for that block.
+    * interface block, this is the ``GLSL_TYPE_INTERFACE`` type for that block.
     *
-    * \sa ir_variable::location
+    * ``ir_variable.location``
     */
    const struct glsl_type *interface_type;
 
@@ -1164,6 +1164,7 @@ nir_is_sequential_comp_swizzle(uint8_t *swiz, unsigned nr_comp)
    return true;
 }
 
+/***/
 typedef struct nir_alu_src {
    /** Base source */
    nir_src src;
@@ -1463,6 +1464,7 @@ typedef enum {
  */
 #define NIR_ALU_MAX_INPUTS NIR_MAX_VEC_COMPONENTS
 
+/***/
 typedef struct nir_op_info {
    /** Name of the NIR ALU opcode */
    const char *name;
@@ -1530,6 +1532,7 @@ nir_op_is_derivative(nir_op op)
    return (nir_op_infos[op].algebraic_properties & NIR_OP_IS_DERIVATIVE) != 0;
 }
 
+/***/
 typedef struct nir_alu_instr {
    /** Base instruction */
    nir_instr instr;
@@ -1564,7 +1567,7 @@ typedef struct nir_alu_instr {
 
    /** Sources
     *
-    * The size of the array is given by nir_op_info::num_inputs.
+    * The size of the array is given by :c:member:`nir_op_info.num_inputs`.
     */
    nir_alu_src src[];
 } nir_alu_instr;
@@ -1874,11 +1877,11 @@ typedef enum {
 } nir_memory_semantics;
 
 /**
- * \name NIR intrinsics semantic flags
+ * NIR intrinsics semantic flags
  *
  * information about what the compiler can do with the intrinsics.
  *
- * \sa nir_intrinsic_info::flags
+ * :c:member:`nir_intrinsic_info.flags`
  */
 typedef enum {
    /**
@@ -2121,7 +2124,7 @@ nir_intrinsic_is_ray_query(nir_intrinsic_op intrinsic)
 typedef enum nir_tex_src_type {
    /** Texture coordinate
     *
-    * Must have nir_tex_instr::coord_components components.
+    * Must have :c:member:`nir_tex_instr.coord_components` components.
     */
    nir_tex_src_coord,
 
@@ -2142,7 +2145,8 @@ typedef enum nir_tex_src_type {
     * Interpolation happens after this conversion so the actual result may be
     * anywhere in the range [0.0, 1.0].
     *
-    * Only valid if nir_tex_instr::is_shadow and must be a float scalar.
+    * Only valid if :c:member:`nir_tex_instr.is_shadow` and must be a float
+    * scalar.
     */
    nir_tex_src_comparator,
 
@@ -2191,16 +2195,16 @@ typedef enum nir_tex_src_type {
 
    /** Texture index offset
     *
-    * This is added to nir_tex_instr::texture_index.  Unless
+    * This is added to :c:member:`nir_tex_instr.texture_index`.  Unless
-    * nir_tex_instr::texture_non_uniform is set, this is guaranteed to be
+    * :c:member:`nir_tex_instr.texture_non_uniform` is set, this is guaranteed
-    * dynamically uniform.
+    * to be dynamically uniform.
     */
    nir_tex_src_texture_offset,
 
    /** Dynamically uniform sampler index offset
     *
-    * This is added to nir_tex_instr::sampler_index.  Unless
+    * This is added to :c:member:`nir_tex_instr.sampler_index`.  Unless
-    * nir_tex_instr::sampler_non_uniform is set, this is guaranteed to be
+    * :c:member:`nir_tex_instr.sampler_non_uniform` is set, this is guaranteed to be
     * dynamically uniform.  This should not be present until GLSL ES 3.20, GLSL
     * 4.00, or ARB_gpu_shader5, because in ES 3.10 and GL 3.30 samplers said
     * "When aggregated into arrays within a shader, samplers can only be indexed
@@ -2345,7 +2349,7 @@ typedef struct nir_tex_instr {
 
    /** Array of sources
     *
-    * This array has nir_tex_instr::num_srcs elements
+    * This array has :c:member:`nir_tex_instr.num_srcs` elements
     */
    nir_tex_src *src;
 
@@ -2420,6 +2424,7 @@ typedef struct nir_tex_instr {
     *
     * The following operations do not require a sampler and, as such, this
     * field should be ignored:
+    *
     *    - nir_texop_txf
     *    - nir_texop_txf_ms
     *    - nir_texop_txs
@@ -2445,7 +2450,7 @@ typedef struct nir_tex_instr {
  * Note that the specific hw/driver backend could require to a sampler
  * object/configuration packet in any case, for some other reason.
  *
- * @see nir_tex_instr::sampler_index.
+ * See also :c:member:`nir_tex_instr.sampler_index`.
  */
 bool nir_tex_instr_need_sampler(const nir_tex_instr *instr);
 
@@ -3731,7 +3736,7 @@ typedef struct nir_shader_compiler_options {
     * If this flag is set, the lowering will be applied to all bit-sizes of
     * these instructions.
     *
-    * \sa ::lower_hadd64
+    * :c:member:`lower_hadd64`
     */
    bool lower_hadd;
 
@@ -3742,7 +3747,7 @@ typedef struct nir_shader_compiler_options {
     * If this flag is set, the lowering will be applied to only 64-bit
     * versions of these instructions.
     *
-    * \sa ::lower_hadd
+    * :c:member:`lower_hadd`
     */
    bool lower_hadd64;
 
@@ -5572,6 +5577,7 @@ bool
 nir_lower_sysvals_to_varyings(nir_shader *shader,
                               const struct nir_lower_sysvals_to_varyings_options *options);
 
+/***/
 enum ENUM_PACKED nir_lower_tex_packing {
    /** No packing */
    nir_lower_tex_packing_none = 0,
@@ -5584,6 +5590,7 @@ enum ENUM_PACKED nir_lower_tex_packing {
    nir_lower_tex_packing_8,
 };
 
+/***/
 typedef struct nir_lower_tex_options {
    /**
     * bitmask of (1 << GLSL_SAMPLER_DIM_x) to control for which