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.

Regards,
Siddharth Mohanty