/retval is not processing the "name" parameter properly.

[kdschlosser]

Describe the bug

The retval directive is used to describe a type of parameterlist. a parameter list is show as follows in the XML schema

  <xsd:complexType name="docParamListType">
    <xsd:sequence>
      <xsd:element name="parameteritem" type="docParamListItem" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
    <xsd:attribute name="kind" type="DoxParamListKind" /> 
  </xsd:complexType>

there is a sequence of parameteritem elements and those are described using this schema

  <xsd:complexType name="docParamListItem">
    <xsd:sequence>
      <xsd:element name="parameternamelist" type="docParamNameList" minOccurs="0" maxOccurs="unbounded" />
      <xsd:element name="parameterdescription" type="descriptionType" />
    </xsd:sequence>
  </xsd:complexType>

the name parameter of the directive is stored in the parametername element which is under parameternamelist element which is seen above. The following the the schema that describes this...

  <xsd:complexType name="docParamNameList">
    <xsd:sequence>
      <xsd:element name="parametertype" type="docParamType" minOccurs="0" maxOccurs="unbounded" />
      <xsd:element name="parametername" type="docParamName" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
  </xsd:complexType>

Now the parametername element has a schema type of docParamName. the schema below describes that type...

  <xsd:complexType name="docParamName" mixed="true">
    <xsd:sequence>
      <xsd:element name="ref" type="refTextType" minOccurs="0" maxOccurs="1" />
    </xsd:sequence>
    <xsd:attribute name="direction" type="DoxParamDir" use="optional" />
  </xsd:complexType>

however it is not referencing what I am placing into the "name" parameter for the directive. I have even tried to use /ref [name] and I end up getting the following error.

warning: unexpected token TK_COMMAND_BS in comment block while parsing the argument of command retval

Here is the c code for the function. This is only the function and the types for everything else does exist. I will put together an example that you can run if it is needed

/**
 * @brief Test function 2
 *
 * Detailed Description of test function 2

 * @param param1       Parameter 1
 * @param param2       Parameter 2
 *
 *
 * @retval lv_obj_point_transform_flag_t The return value is a 32 bit unsigned integer
 *
 *
 * @exception assert   Test Exception
 */
lv_obj_point_transform_flag_t function_test2(lv_property_t param1, lv_draw_arc_dsc_t param2);

If I don't use the /ref directive this is what is output for the function.

<memberdef kind="function" id="test_8h_1af27754a053b2e8ddf260d0f6483c7752" prot="public" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
        <type>lv_obj_point_transform_flag_t</type>
        <definition>lv_obj_point_transform_flag_t function_test2</definition>
        <argsstring>(lv_property_t param1, lv_draw_arc_dsc_t param2)</argsstring>
        <name>function_test2</name>
        <param>
          <type><ref refid="structlv__property__t" kindref="compound">lv_property_t</ref></type>
          <declname>param1</declname>
        </param>
        <param>
          <type><ref refid="structlv__draw__arc__dsc__t" kindref="compound">lv_draw_arc_dsc_t</ref></type>
          <declname>param2</declname>
        </param>
        <briefdescription>
<para>Test function 2. </para>
        </briefdescription>
        <detaileddescription>
<para>Detailed Description of test function 2</para>
<para><parameterlist kind="param"><parameteritem>
<parameternamelist>
<parametername>param1</parametername>
</parameternamelist>
<parameterdescription>
<para>Parameter 1 </para>
</parameterdescription>
</parameteritem>
<parameteritem>
<parameternamelist>
<parametername>param2</parametername>
</parameternamelist>
<parameterdescription>
<para>Parameter 2</para>
</parameterdescription>
</parameteritem>
</parameterlist>
<parameterlist kind="retval"><parameteritem>
<parameternamelist>
<parametername>lv_obj_point_transform_flag_t</parametername>
</parameternamelist>
<parameterdescription>
<para>The return value is a 32 bit unsigned integer</para>
</parameterdescription>
</parameteritem>
</parameterlist>
<parameterlist kind="exception"><parameteritem>
<parameternamelist>
<parametername>assert</parametername>
</parameternamelist>
<parameterdescription>
<para>Test Exception </para>
</parameterdescription>
</parameteritem>
</parameterlist>
</para>
        </detaileddescription>
        <inbodydescription>
        </inbodydescription>
        <location file="test.h" line="314" column="31" declfile="test.h" declline="314" declcolumn="31"/>
      </memberdef>

Now what is important about this XML output is this section..

        <param>
          <type><ref refid="structlv__draw__arc__dsc__t" kindref="compound">lv_draw_arc_dsc_t</ref></type>
          <declname>param2</declname>
        </param>

the type element uses this schema

  <xsd:complexType name="linkedTextType" mixed="true">
    <xsd:sequence>
    <xsd:element name="ref" type="refTextType" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
  </xsd:complexType>

which has a ref element that has the exact same type which is refTextType

I would think that I should not have to use the /ref directive in order to reference what gets placed in the name parameter for the /retval directive. It should automatically locate the compound or member if one exists. It appears to work properly for the parameters.

[albert-github]

I looked at the warning:

warning: unexpected token TK_COMMAND_BS in comment block while parsing the argument of command retval

and it is familiar, but I cannot reproduce it with the current doxygen version (1.12.0) and the information provided (e.g. no settings file, no mentioning of the used doxygen version). To be able to reproduce the problem:

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).
• Please also specify the full doxygen version used (doxygen -v).