On Tue, 24 Jun 2025 at 13:46, Siddharth Mohanty <neosiddharth_at_[hidden]>
wrote:

> I think I failed to clearly motivate and formalize my idea, since I wanted
> to start it off with this high level overview. Ultimately, I'd like to
> pursue 2 classes of [[doc]] attribute. By having the raw string literal
> syntax I described in my earlier email, we can allow a quick adoption path
> from doxygen comments. These would be purely information since they are
> just loosely structured text as you mentioned. The "checking" I referred to
> would come from more structured docs, e.g.
>
> ```cpp
> [[doc::brief("Allocates memory on the heap")]]
> [[doc::param(bytes, "The number of bytes to allocate")]]
> [[doc::return("A pointer to the heap or nullptr in case of an exception")]]
> ```
>

You will be able to do this in C++26 using annotations, and reflecting them:
https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2025/p3394r3.html



>
> This would have major upside over comments since it allows us to document
> specific parts of the function(see the doc::param). Circling back to my
> "checked" documentation, we could add in trivial contracts inside the docs,
> preventing accuracy from waning over time, e.g.
>
> ```cpp
> [[doc::param(ptr, "The Pointer to Free", ptr != nullptr)]]
> void free(void *ptr);
> ```
>

Why would you want to state the contract as documentation, instead of as a
contract?
https://en.cppreference.com/w/cpp/language/contracts.html