Adding support for C++ concepts (Origin: bugzilla #499352)

[doxygen]

status NEW severity enhancement in component general for ---
Reported in version unspecified on platform Other
Assigned to: Dimitri van Heesch

On 2007-11-24 14:37:22 +0000, Sylvain Pion wrote:

It would be nice if doxygen would support C++ concepts, in the form
specified by the coming C++0x standard.  Many C++ libraries already
use concepts (including the STL), and the proper code format is going
to be this one.  It would be nice to have doxygen to understand them.

See also the feature request there:
http://conceptgcc.wordpress.com/2007/04/24/wanted-doxygen-hacker/

More information on C++0x concepts can be found or reached at:
http://www.generic-programming.org/

[lrineau]

Hi @doxygen. Is this issue still a valid one?

In addition to contracts (see #6702), C++20 will also have concepts. Those two features will change the signature of C++ functions and functions templates.

That will probably is a big effort, to make Doxygen compatible with them.

1. Make the parser accept the new language features.
2. Accept contracts as part of the signature of a function.
3. Allow the documentation of C++ concepts.
4. Change the produced documentation, so that
   • there are links to the documentation of used concepts,
   • contracts are displayed, as suggested in Support for C++20 design by contract #6702.

Cc: @afabri

[KantarBruceAdams]

Contracts are just attributes which Doxygen should already be able to parse if it can parse C++11. Extracting useful content from them is another matter.
Attributes aren't supposed to change the meaning of a program (they are more like compiler hints). The signature of functions does not change.

I think concepts is a much bigger change than contracts.
Concepts introduces significant new syntax (including a new terse syntax hot off the press at the 2018 San Diego meeting).
If using libclang parsing will come for free but as far as I know using libclang is still optional so Doxygen's own parser will have to be updated to handle that.

[marehr]

Current workaround

We currently document concepts like interfaces, because they are documentation-wise quite close to interfaces.

namespace ns
{
/*!\interface   ns::Arithmetic <>
 * \brief       A type that satisfies std::is_arithmetic_v<t>.
 * \sa          http://en.cppreference.com/w/cpp/types/is_arithmetic
 */
//!\cond
template <typename t>
concept Arithmetic = std::is_arithmetic_v<t>;
//!\endcond

/*!\interface ns::Same <>
 * \brief The concept `ns::Same<T, U>` is satisfied if and only if T and U denote the same type.
 * \sa https://en.cppreference.com/w/cpp/concepts/Same
 */
//!\cond
template <class T, class U>
concept Same = std::is_same_v<T, U>;
//!\endcond
} // namespace ns

/*!\brief Explanation.
 * \implements Range  // declare that this type models the concept.
 */
struct my_container
{
  void begin();
  void end();
};

Desired manual definition

It would suffice for us to only be able to manually define them:

namespace ns
{
/*!\concept   ns::Arithmetic <>
 * \brief       A type that satisfies std::is_arithmetic_v<t>.
 * \sa          http://en.cppreference.com/w/cpp/types/is_arithmetic
 */
//!\cond
template <typename t>
concept Arithmetic = std::is_arithmetic_v<t>;
//!\endcond

/*!\concept ns::Same <>
 * \brief The concept `std::Same<T, U>` is satisfied if and only if T and U denote the same type.
 * \sa https://en.cppreference.com/w/cpp/concepts/Same
 */
//!\cond
template <class T, class U>
concept Same = std::is_same_v<T, U>;
//!\endcond

/*!\concept ns::Range <>
 * \brief Description
 */
//!\cond
template <class R>
concept Range = requires(R r)
{
    { r.begin() };
    { r.end() };
};
//!\endcond

} // namespace ns

/*!\brief Explanation.
 * \models Range  // declare that this type models the concept.
 */
struct my_container
{
  void begin();
  void end();
};

This would cover like 70% of our concept use-cases.

If you want I can give you more use-cases.

C++20 concepts have been added to Clang 10, so the parser is already there, just need to hook Doxygen to it.

[mpusz]

The following code:

/**
 * @brief A dimension of a derived quantity
 *
 * Expression of the dependence of a quantity on the base quantities (and their base dimensions) of a system of
 * quantities as a product of powers of factors corresponding to the base quantities, omitting any numerical factors.
 * A power of a factor is the factor raised to an exponent.
 * 
 * A derived dimension can be formed from multiple exponents (i.e. velocity is represented as "exp<L, 1>, exp<T, -1>").
 * It is also possible to form a derived dimension with only one exponent (i.e. frequency is represented as just
 * "exp<T, -1>").
 * 
 * @note This class template is used by the library engine and should not be directly instantiated by the user.
 * 
 * @tparam E a first exponent of a derived dimension
 * @tparam ERest zero or more following exponents of a derived dimension
 */
template<Exponent E, Exponent... ERest>
  requires (BaseDimension<typename E::dimension> && ... && BaseDimension<typename ERest::dimension>)
struct derived_dimension_base : downcast_base<derived_dimension_base<E, ERest...>> {
  using exponents = exp_list<E, ERest...>;
};

results with:

warning: Found ';' while parsing initializer list! (doxygen could be confused by a macro call without semicolon)

while such a definition:

  template<typename D2, typename U2, typename Rep2>
  [[nodiscard]] friend constexpr bool operator==(const quantity& lhs, const quantity<D2, U2, Rep2>& rhs)
    requires equivalent_dim<D, D2> &&
            detail::basic_arithmetic<Rep, Rep2> &&
            std::equality_comparable_with<Rep, Rep2>
  {
    using cq = common_quantity<quantity, quantity<D2, U2, Rep2>>;
    return cq(lhs).count() == cq(rhs).count();
  }

results with:

warning: documented symbol 'constexpr friend bool D2 &&detail::basic_arithmetic< Rep, Rep2 > && units::quantity::std::equality_comparable_with< Rep, Rep2 >' was not declared or defined.

You can find more interesting use cases in this repo: https://github.com/mpusz/units which uses C++20 features and targets addition in C++23 ;-)

[ninkibah]

I found a workaround for specifying requires clauses by using a macro for the requires condition:

#define NOT_AN_INT !std::is_same_v<T>
template<typename T>
  requires NOT_AN_INT
void f(T obj);

This will be parsed correctly by Doxygen, and the function will be outputted with requires NOT_AN_INT in the output.
This is not ideal, of course, but for now it's the only possibility I've found.

[h-2]

Any news here?

[doxygen]

I plan to start working on adding support for concepts soon.
If anyone knows good publicly available projects to test on, please let me know.
Suggestions on how to best represent concepts and required clauses in the doxygen output are also welcome.

[ninkibah]

After I found my #define trick, I was able to generate reasonable documentation for functions with requires clauses. I'm a complete Doxygen novice, and I only generate XML which is then passed on to Sphinx, via the breathe extension, so I can't tell what tool is doing what.
BUT, it appears that the "requires NOT_AN_INT" is being read as if it was a noexcept or override marker. Initially this is fine.

If you want initial examples of the different requires clauses, here's some I've modifed slightly from Rainer Grimm's new book on C++20:

// Requires clause
template<typename T>
  requires std::integral<T>
auto add(T a, T b) {
  return a + b;
}

// Trailing requires clause
template<typename T>
auto add1(T a, T b) requires std::integral<T> {
  return a + b;
}

// Constained template parameter
template<std::integral T>
auto add2(T a, T b) {
  return a + b;
}

// Abbreviated function template
auto add3(std::integral auto a, std::integral auto b) {
  return a + b;
}

As far as I know, these are all the possible syntaxes. I think class templates only have requires clauses and constrained template parameters.

Best of luck!

[marehr]

I plan to start working on adding support for concepts soon.
If anyone knows good publicly available projects to test on, please let me know.
Suggestions on how to best represent concepts and required clauses in the doxygen output are also welcome.

As I stated before in this thread, we use Concepts quite heavily. If you search for SEQAN3_CONCEPT in https://github.com/seqan/seqan3/ you will find a pool of different examples and the corresponding (hand-written) documentation, where we use \interface as a work-around for concepts. (e.g. we replace in the navbar all occurrences of interface with concept)

I would also offer our help to test the things out!

I think the most useful thing for the first-step would be to just display the concept-definitions as they are and to link all the included entities as in https://en.cppreference.com/w/cpp/ranges/input_range.

For "usages" it would suffice in the beginning if the short-notation and requires-expression would work
https://en.cppreference.com/w/cpp/ranges/iota_view

For a comprehensive overview of the possible syntaxes see https://en.cppreference.com/w/cpp/language/constraints.

---

EDIT:

As far as I know, these are all the possible syntaxes. I think class templates only have requires clauses and constrained template parameters.

And all combinations of them:

template<std::integral T>
  requires std::integral<T>
auto add(T a, std::integral auto b) requires std::integral<T> {
  return a + b;
}

[milasudril]

I think:

There should be a separate paragraph for the requirements. It could be formatted as unordered or ordered list. The latter would be good if the documentation needs to refer to specific requirement. However, I think this should be user configurable.

Documenting concepts themself should be a formatted expression list.

I think it is a good idea to be able to document individual requirements also.