I was thinking about how C++ handles documentation. We currently rely on comment-parsing, but this is flawed since comments aren't a checked part of the language and can easily become inaccurate.

I'm imagining a simple attribute, maybe [[doc]], that would let the compiler and static-analyzers see and understand documentation. This could lead to much tighter integration with IDEs and better static analysis. This would be reminiscent of the existing [[deprecated]] attribute but instead of a warning, it would be purely informational.

We could even have a syntax like the example below to formalize our conventional doc comments:

[[doc(R"
@brief This function allocates memory on the heap.
@param bytes The number of bytes to allocate.
@return A pointer to the heap or nullptr in case of exception.

")]]
void *malloc(size_t bytes);

I'd appreciate feedback on whether this is a good enough idea to turn into a proposal.