Doxygen: Support for C++20 design by contract

[KantarBruceAdams]

Contracts have been voted into C++20 such that you may now write code like:

void push(int x, queue & q)
  [[expects: !q.full()]]
  [[ensures: !q.empty()]]
{
  //...
  [[assert: q.is_valid()]];
  //...
}

At present we use @pre and @post & @invariant tags to document contracts using Doxygen.
This leads to the following feature request:

1) Doxygen should parse expects and ensures attributes and treat them exactly as if I'd written:

///
/// @pre 
/// @code !q.full() @endcode
///
/// @post 
/// @code !q.empty() @endcode
///
void push(int x, queue & q)
  [[expects: !q.full()]]
  [[ensures: !q.empty()]]
{
  //...
  [[assert: q.is_valid()]];
  //...
}

2) Doxygen should consider using @expects and @ensures as aliases or replacements for @pre and @post.
There is still a place for hand documented contracts (i.e current usage) even with C++20.
Some contracts are hard to express in code. Adding commentary to a contract to explain it can be useful.

3) Doxygen might also consider adding an alternative way to literately document attributes with a more compact syntax. E.g.

void push(int x, queue & q)
  [[expects: !q.full()]]   /// the queue must not be full
  [[ensures: !q.empty()]]  /// following the operation the qeue cannot be empty

Might be equivalent to:

///
/// @pre 
/// The queue must not be full
/// @code !q.full() @endcode
///
/// @post 
/// Following the operation the qeue cannot be empty.
/// @code !q.empty() @endcode
///
void push(int x, queue & q)
  [[expects: !q.full()]]        
  [[ensures: !q.empty()]]  

[ghost]

Contracts were voted off the C++20 at 2019 Cologne meeting and will be put into a separate Contracts TS in the future.

[albert-github]

@Lyberta for future reference can you give a reference to where it is stated that contracts were voted off at the C++20 at 2019 Cologne meeting.

[ghost]

Well, the popular source of information is here but the formal reference is here:

CWG motion 16: P1823R0 "Remove contracts"

[louwers]

Since this didn't make C++20, this should be closed for now right?

[KantarBruceAdams]

I think contracts are still in the plan they've just been pushed back to C++23 (or possibly later) until some imperfections can be ironed out.