Allow the annotations for indiviual constraints in a concept

[akrzemi1]

Here is an example of the current "manual" documentation of my concept: https://github.com/akrzemi1/markable/blob/master/documentation/reference.adoc#concept-mark_policy.

Generally, every function that I list as constraint potentially has its semantic constraints: preconditions, postconditions, complexity, and some other relevant context. This reflects the fact that concepts come with not only syntactic constraints but also (statically unenforceable) semantic constraints.

Basically, I need to being able to describe the same things for each template constraint, that I use for describing class member functions and member types.

[alandefreitas]

The main blocker here is parsing expressions. For now, all we have there are strings.

[akrzemi1]

I see.
This reminds me of the times around 2010, where two visions of concepts were considered:

• valid expressions,
• function signatures.

The proponents of "function signatures" were criticizing "valid expressions" that they would be more difficult to consume by tooling. It looks like they were right.

But is it possible, as an intermediate solution, to just recognize individual constraints, even if each is just a string, and allow entering the /** annotations */ for each? Even if this is just @par?

[alandefreitas]

But is it possible, as an intermediate solution, to just recognize individual constraints, even if each is just a string, and allow entering the /** annotations */ for each? Even if this is just @Par?

We'd have to see what clang provides us. I suspect recognizing the individual constraints will be easier, and getting annotations for each is going to be harder (meaning: unavailable and we'll have to implement this upstream on llvm-project).😅

FYI @mizvekov

[mizvekov]

We'd have to see what clang provides us. I suspect recognizing the individual constraints will be easier, and getting annotations for each is going to be harder (meaning: unavailable and we'll have to implement this upstream on llvm-project).😅

Yes, we do break down the constraints into their individual atoms, and parsing the AST until that point is relatively straightforward.

However, as far as I know we don't support annotations on expressions in clang, they are only attached to declarations.

[akrzemi1]

I do not fully understand the nomenclature being used, so let me give an example to see if we are talking about the same thing.

/** A concept representing non-owing pointer like types 
 */
template <typename T>
concept PointerLike = requires(T p)
{
  typename value_type;

  /** Used to query if the pointer represents a valid object
  */
  { p } -> std::convertible_to<bool>;

  /** Used to access the pointed-to object
    @par precondition
    `bool(p)` is `true`.
  */
  { *p } -> std::same_as<value_type&>;
};

I guess that translates into:

• it is enough to annotate "full constraints": no need to annotate "atomic" constraints,
• It is not necessary to parse/validate/recognize names and expressions; as a bare minimum, just allow me to insert paragraphs per full constraint.

[mizvekov]

Yeah, makes sense, that clarifies it thanks.

Those are modeled as Requirements, defined in clang/include/clang/AST/ExprConcepts.h, but they are technically not expressions themselves.

But still clang doesn't track doxygen-style comment blocks attached to them.

[alandefreitas]

We could try to include this upstream.

To confirm, in

  /** Used to access the pointed-to object
    @par precondition
    `bool(p)` is `true`.
  */

this seems to be creating two sources of truth for this precondition.

Isn't this more appropriate as the documentation of operator*? Or a precondition of operator* when this is available.

[akrzemi1]

I don't understand. What would be the second source of truth?

Instead, let me explain what is my intent. This annotation in the concept means:

1. The "algorithms" constrained by this concept will comply with the contract and not call *p unless they are sure that bool(p) is true.

2. A type that models this concept may look like this:

template <typename T>
struct chacking_ponter
{
  using value_type = T;
  value_type* _ptr;

  explicit operator bool() const { return _ptr != nullptr; } 

  value_type& operator*() const {  // <-- no precondition!
    if (_ptr == nullptr) throw bad_argument{};
    return *_ptr;
  }  
};

This modelling is fine: the algorithms, as per the concept's contract, avoid dereferencing a null pointer, yet the type knows what to do upon the null pointer.

[alandefreitas]

Oh... Sorry. Of course. The classes for the concept aren't necessarily provided by the library. Yes.

Yes. I think it's worth trying to provide this feature in the LLVM project when we can get to it.

For now, the least-bad solution is to include this information in the concept's documentation.