As others mentioned, DoxyGen is a thing that's respected by most tools.
Maybe loose text formatting is not the best way to approach your proposal.
To those who are familiar with SAL, a simple annotation language would be
feasible. I don't know if it should be part of the C++ standard. I have
great time using SAL, and it is helpful. Standardising something
**similar** to SAL could be something desirable. However, adding something
to the standard means the feature is widely used by developers. So if I
wanted to make a proposal about code safety and documentation, I would
reach for a solution similar to SAL and add actual annotations that would
be easy to implement in various toolings. Examples include an allocator
annotation, not null, can be null/optional and such stuff. Tell me what you
think about it.

PS: I know I replied to the wrong message, not sure how else to do it from
a mobile device though. Sorry about that.

Tymi.


On Tue, 24 Jun 2025, 12:23 , <std-proposals-request_at_[hidden]> wrote:

> Send Std-Proposals mailing list submissions to
> std-proposals_at_[hidden]
>
> To subscribe or unsubscribe via the World Wide Web, visit
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
> or, via email, send a message with subject or body 'help' to
> std-proposals-request_at_[hidden]
>
> You can reach the person managing the list at
> std-proposals-owner_at_[hidden]
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Std-Proposals digest..."
>
>
> Today's Topics:
>
> 1. Re: I have a span but I need a container
> (Frederick Virchanza Gotham)
> 2. Re: I have a span but I need a container (Jason McKesson)
> 3. Standardizing Code Documentation (Siddharth Mohanty)
> 4. Re: Standardizing Code Documentation (Jonathan Wakely)
> 5. Re: Standardizing Code Documentation (Sebastian Wittmeier)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Mon, 23 Jun 2025 19:24:47 +0100
> From: Frederick Virchanza Gotham <cauldwell.thomas_at_[hidden]>
> To: "std-proposals_at_[hidden]" <std-proposals_at_[hidden]>
> Subject: Re: [std-proposals] I have a span but I need a container
> Message-ID:
> <
> CALtZhhN8R3BZKB1G2ESDLeMCeZ3HBuQrjoWKPRKYs-4iXHfxqA_at_[hidden]>
> Content-Type: text/plain; charset="utf-8"
>
> To keep the "object model" people happy, there could be a standard library
> type as follows:
>
> std::basic_string_nocopy;
>
> Its constructor could be:
>
> template<size_t N>
> consteval basic_string_nocopy( value_type const (&arg)[N] );
>
> And it could have a member function called "str" which returns a reference
> to a const std::string.
>
> The standard could simply mandate that when the string_nocopy object is
> created, an std::string object is also created, and the lifetime of the
> std::string object is the same as the lifetime of the string_nocopy object.
> Furthermore the standard could mandate that explicitly calling the
> std::string destructor on the enclosed std::string object is undefined
> behavior, just in case any wild west gun slinger tries something like:
>
> string_nocopy obj("Hello");
> string const &s = obj.str();
> const_cast<string&>(s)->~string();
> -------------- next part --------------
> HTML attachment scrubbed and removed
>
> ------------------------------
>
> Message: 2
> Date: Mon, 23 Jun 2025 16:51:05 -0400
> From: Jason McKesson <jmckesson_at_[hidden]>
> To: std-proposals_at_[hidden]
> Subject: Re: [std-proposals] I have a span but I need a container
> Message-ID:
> <CANLtd3Xe2-=
> QJYkN5dpJDmnshdoHM+82UGftGpbPKBStpejtYQ_at_[hidden]>
> Content-Type: text/plain; charset="UTF-8"
>
> On Mon, Jun 23, 2025 at 2:24?PM Frederick Virchanza Gotham via
> Std-Proposals <std-proposals_at_[hidden]> wrote:
> >
> > To keep the "object model" people happy, there could be a standard
> library type as follows:
> >
> > std::basic_string_nocopy;
> >
> > Its constructor could be:
> >
> > template<size_t N>
> > consteval basic_string_nocopy( value_type const (&arg)[N] );
> >
> > And it could have a member function called "str" which returns a
> reference to a const std::string.
> >
> > The standard could simply mandate that when the string_nocopy object is
> created, an std::string object is also created, and the lifetime of the
> std::string object is the same as the lifetime of the string_nocopy object.
> Furthermore the standard could mandate that explicitly calling the
> std::string destructor on the enclosed std::string object is undefined
> behavior, just in case any wild west gun slinger tries something like:
> >
> > string_nocopy obj("Hello");
> > string const &s = obj.str();
> > const_cast<string&>(s)->~string();
>
> I don't see how this addresses any of the problems with the proposal.
> The proposal is not specific to `std::string`; that's just an example.
> Furthermore, I don't see how this would be used even within the
> example you gave.
>
>
> ------------------------------
>
> Message: 3
> Date: Tue, 24 Jun 2025 02:14:51 -0700
> From: Siddharth Mohanty <neosiddharth_at_[hidden]>
> To: std-proposals_at_[hidden]
> Subject: [std-proposals] Standardizing Code Documentation
> Message-ID:
> <
> CAL-9rtuf5pxrqGagPg-mu6KJmT-7NCESJkjpkqpQyPTFwgLinQ_at_[hidden]>
> Content-Type: text/plain; charset="utf-8"
>
> 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
> -------------- next part --------------
> HTML attachment scrubbed and removed
>
> ------------------------------
>
> Message: 4
> Date: Tue, 24 Jun 2025 11:07:15 +0100
> From: Jonathan Wakely <cxx_at_[hidden]>
> To: "C++ Proposals" <std-proposals_at_[hidden]>
> Subject: Re: [std-proposals] Standardizing Code Documentation
> Message-ID:
> <CAJcCCPO76oRYeb5rSiQwQDkBhoWV7gyAky=
> 7f-D90AnuPWK9Jg_at_[hidden]>
> Content-Type: text/plain; charset="utf-8"
>
> 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.
>
> >
> -------------- next part --------------
> HTML attachment scrubbed and removed
>
> ------------------------------
>
> Message: 5
> Date: Tue, 24 Jun 2025 12:14:53 +0200
> From: Sebastian Wittmeier <wittmeier_at_[hidden]>
> To: std-proposals_at_[hidden] <std-proposals_at_[hidden]>
> Subject: Re: [std-proposals] Standardizing Code Documentation
> Message-ID:
> <
> zarafa.685a7a9d.152c.0a6080c86ed4ae55_at_lvps176-28-11-36.dedicated.hosteurope.
> >
>
> Content-Type: text/plain; charset="utf-8"
>
> So one (the only?) difference would be that the attributes belong to a
> certain entity like a function or class?
> ?
> -----Urspr?ngliche Nachricht-----
> Von:Siddharth Mohanty via Std-Proposals <std-proposals_at_[hidden]>
> Gesendet:Di 24.06.2025 11:15
> Betreff:[std-proposals] Standardizing Code Documentation
> An:std-proposals_at_[hidden];
> CC:Siddharth Mohanty <neosiddharth_at_[hidden]>;
>
>
> 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
>
>
>
>
> --
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>
>
>
> -------------- next part --------------
> HTML attachment scrubbed and removed
>
> ------------------------------
>
> Subject: Digest Footer
>
> Std-Proposals mailing list
> Std-Proposals_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals
>
>
> ------------------------------
>
> End of Std-Proposals Digest, Vol 75, Issue 97
> *********************************************
>