Sharing learnings on getting a C++ template function to work

[kaycebasques]

Hello! We're using Doxygen & Breathe with quite a bit of success over in the Pigweed docs (https://pigweed.dev). Thanks for maintaining this project.

I was having trouble getting Breathe/Doxygen to work with a C++ template function. I just figured it out. I spent quite a while trying to get this working, so I figured I'd share my learnings.

I am a C++ and Doxygen/Breathe n00b (I'm a technical writer) so please go easy on me if I have made any super n00b assumptions/mistakes

Solution

.. doxygennamespace:: pw::base64
   :members:

Debugging process

(I wrote this ten minutes ago, before I found the solution)

I'm having trouble getting Doxygen / Breathe to pick up this C++ template function:

/// Creates a `pw::InlineString<>` large enough to hold
/// `kMaxBinaryDataSizeBytes` of binary data when encoded as Base64 and encodes
/// the provided span into it.
///
/// If the data is larger than `kMaxBinaryDataSizeBytes`, an assertion fails.
template <size_t kMaxBinaryDataSizeBytes>
inline InlineString<EncodedSize(kMaxBinaryDataSizeBytes)> Encode(
    span<const std::byte> binary) {
  InlineString<EncodedSize(kMaxBinaryDataSizeBytes)> output;
  Encode(binary, output);
  return output;
}

https://cs.opensource.google/pigweed/pigweed/+/537df1014f69621c98c22d1488fe8db6bc621e64:pw_base64/public/pw_base64/base64.h;l=101

Here are the things I've tried:

Clang parsing in Doxyfile

CLANG_ASSISTED_PARSING = YES

Basic namespaced signature

.. doxygenfunction:: pw::base64::Encode(span<const std::byte> binary)

The output suggests that Doxygen/Breathe is aware of the template function:

Warning, treated as error:
.../docs.rst:21:doxygenfunction: Unable to resolve function "pw::base64::Encode" with arguments (span<const std::byte>) in doxygen xml output for project "Pigweed" from directory: ./../../../doxygen/xml/.
Potential matches:
- size_t Encode(span<const std::byte> binary, span<char> output_buffer)
- template<size_t kMaxBinaryDataSizeBytes> InlineString<EncodedSize(kMaxBinaryDataSizeBytes)> Encode(span<const std::byte> binary)
- void Encode(span<const std::byte> binary, InlineString<> &output)
- void Encode(span<const std::byte> binary, char *output)
ninja: build stopped: subcommand failed.

When I look into the Doxygen XML it seems like the function is also there:

      <memberdef kind="function" id="base64_8h_1a1929833d421665e414e33f1b4c845a64" prot="public" static="no" const="no" explicit="no" inline="yes" virt="non-virtual">
        <templateparamlist>
          <param>
            <type>size_t</type>
            <declname>kMaxBinaryDataSizeBytes</declname>
            <defname>kMaxBinaryDataSizeBytes</defname>
          </param>
        </templateparamlist>
        <type><ref refid="string_8h_1a671f692f54aaaf6a340b6c3f3d9d4974" kindref="member">InlineString</ref>&lt; EncodedSize(kMaxBinaryDataSizeBytes)&gt;</type>
        <definition>InlineString&lt; EncodedSize(kMaxBinaryDataSizeBytes)&gt; pw::base64::Encode</definition>
        <argsstring>(span&lt; const std::byte &gt; binary)</argsstring>
        <name>Encode</name>
        <qualifiedname>pw::base64::Encode</qualifiedname>
        <param>
          <type>span&lt; const std::byte &gt;</type>
          <declname>binary</declname>
        </param>
        <briefdescription>
        </briefdescription>
        <detaileddescription>
<para>Creates a <computeroutput><ref refid="string_8h_1a671f692f54aaaf6a340b6c3f3d9d4974" kindref="member">pw::InlineString</ref>&lt;&gt;</computeroutput> large enough to hold <computeroutput>kMaxBinaryDataSizeBytes</computeroutput> of binary data when encoded as Base64 and encodes the provided span into it.</para>
<para>If the data is larger than <computeroutput>kMaxBinaryDataSizeBytes</computeroutput>, an assertion fails. </para>
        </detaileddescription>
        <inbodydescription>
        </inbodydescription>
        <location file=".../pigweed/pw_base64/public/pw_base64/base64.h" line="116" column="21" bodyfile=".../pigweed/pw_base64/public/pw_base64/base64.h" bodystart="116" bodyend="121"/>
      </memberdef>

Signature that Doxygen/Breathe suggested

It seems like Encode needs to be namespaced but I tried it verbatim just in case:

.. doxygenfile:: template<size_t kMaxBinaryDataSizeBytes> InlineString<EncodedSize(kMaxBinaryDataSizeBytes)> Encode(span<const std::byte> binary)

That also did not work. I don't have the exact output anymore but I believe it was something along the lines of Doxygen cannot find function "template<size_t kMaxBinaryDataSizeBytes" (note how the quotes do not have the full signature)

[kaycebasques]

This discussion is technically closed because I found an answer myself, but I'll leave the discussion open just to put it on people's radars