Help needed with including example program snippets in the documentation

[MyNameIsTrez]

Context

StreamHPC has this internal GitLab issue:

Example files in the example folder are compilable, executable, and typically tested before merging, making them more reliable and maintainable compared to inline examples.

To improve consistency and maintainability, it might be beneficial to directly link these tested example files to the Doxygen documentation, rather than duplicating them or writing examples inline.

This is a small part of a bigger GitLab issue about adding more examples to the libraries we maintain.

Examples would become much more valuable if they're used for snippets in the documentation, since users would be able to click a link near the snippet to see the full example program.

Right now the example programs don't assert() the values they print, but if that's also done later, we can guarantee that the output of the examples stays correct for the docs.

My findings

• The few example programs that we have only print the output, without assert()ing the correctness of the output.
• I experimented with \example, \include, \snippet, and \dontinclude, but each of them seem to have problems:
  • \example and \include only allow you to paste the entire contents of a file into a code block.
  • Multiple \snippets can't be combined into a single code block.
  • \dontinclude uses \skip and \until, but their search pattern is displayed in the code block.

All of the repositories only use \code right now

Searching \code in our repositories finds 645 results:

• hipCUB: 2 results
• hipRAND: 2 results
• rocPRIM: 218 results
• rocRAND: 2 results
• rocThrust: 421 results

@code is used 3 times in hipCUB, but none of \example, @example, \snippet, @snippet, \dontinclude, @dontinclude, \include, nor @include are used in any of the repositories.

Example of \snippet

\snippet is used by putting markers around the example code (this example/example_type_traits_interface.cpp hasn't been pushed upstream yet):

//! [Your type definition]
// Your type definition
struct custom_float_type
{};
//! [Your type definition]

//! [Implement the traits]
// Implement the traits
template<>
struct rocprim::traits::define<custom_float_type>
{
    using is_arithmetic = rocprim::traits::is_arithmetic::values<true>;
    using number_format
        = rocprim::traits::number_format::values<number_format::kind::floating_point_type>;
    using float_bit_mask = rocprim::traits::float_bit_mask::values<uint32_t, 10, 10, 10>;
};
//! [Implement the traits]

/// The example below demonstrates how to implement traits for a custom floating-point type.
/// \snippet example_type_traits_interface.cpp Your type definition
/// \snippet example_type_traits_interface.cpp Implement the traits

Using markers is much better than hardcoding line numbers, since it prevents newly added lines at the top of the file from affecting the snippets.

It would be really nice if these snippets could be merged into a single code block:

I tried reusing the same snippet marker name for both snippets, but Doxygen throws an error that the same marker name appears more than twice.

\snippet{lineno} and \snippet{trimleft} simply don't seem to do anything for me, which is annoying. These bugs would most likely be fixed by updating to a newer version, since our projects all use Doxygen 1.9.4. This GitHub discussion its author states that a similar bug was fixed at some point, and doesn't appear in version 1.11.0 anymore. But I don't think updating Doxygen would help with merging snippets into a single block of code.

I'm posting my findings here since I am not very familiar with Doxygen, and I imagine this idea has been looked into before. If no one on the rocm-docs-core team knows of an easy workaround, I can post this issue in the Doxygen repository.

[ppanchad-amd]

Hi @MyNameIsTrez. Internal ticket has been created to address this issue in the docs. Thanks!