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")]]
```

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);
```

I hope this more long term expansion of my idea makes my plan more sensible.

On Tue, Jun 24, 2025 at 3:07 AM Jonathan Wakely <cxx_at_[hidden]> wrote:

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