On Tue, 24 Jun 2025, 10:15 Siddharth Mohanty via Std-Proposals, <
std-proposals_at_[hidden]> wrote:

> 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.
>

So are you proposing that they be checked?


> 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.
>

So not checked?

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.
>

Are you proposing to standardize the tags like @param and @return ?

>
> ")]]
> void *malloc(size_t bytes);
>
> I'd appreciate feedback on whether this is a good enough idea to turn into
> a proposal.
>


I'm not seeing a concrete benefit to doing this. Why is it better than the
comments we use now?

Is the tighter integration with IDEs and tools likely? Would it enable
anything that isn't possible today by inspecting comments? It would still
just be loosely structured text, right?

There has been a proposal on this list before to just standardize Doxygen,
i.e. using comments rather than your [[doc]] idea.

>