What does the attribute do? Expose identifiers and other internas of the implementation into the documentation? Why is the attribute needed, or when would you not want to do it?  - Implementation secrets  - Implementation Encapsulation  - Badly chosen names?   -----Ursprüngliche Nachricht----- Von:Filip <fph2137_at_[hidden]> Gesendet:Sa 22.03.2025 13:32 Betreff:Re: [std-proposals] Standardizing doc comments An:std-proposals_at_[hidden]; CC:Sebastian Wittmeier <wittmeier_at_[hidden]>; std-proposals_at_[hidden]; To me documentation is usually outdated and inaccurate, I would prefer to have attribute used and any documentation generator to just read the functions. After all it’s reading the file anyway so why not just read the code?  [[documentable]] void Procedure();  That attribute could indicate that functions inside this function can be used for their names and that should explain what the code is doing.  The benefit is that it’s an actual code that is being run and you don’t have to update it in every place.  At some point you obviously get to the function that wouldn’t have this attribute which would be an actual implementation that’s low level.  The documentation depends on good naming just as much as the code so there’s no motivation on my part to document the code that could be written with the attitude that it will be read more often. Cheers, Filip Wiadomość napisana przez Sebastian Wittmeier via Std-Proposals <std-proposals_at_[hidden]> w dniu 22 mar 2025, o godz. 13:15:  A bit of guidance could help.   Also it could be that some tools want to further annotate or read annotations. The most standard way is through attributes, but if comments are used, should certain comment characters be reserved or at least intended for specific usage.   One character often used is @ Or strings like NOLINTNEXTLINE, coverity[ Or <auto-generated> Or clang-format-, eslint-, prettier- Or TODO:, FIXME:, BUG:   Another point is how to signify comment blocks. Comment lines belonging together. You can do C++ block comments, but perhaps also 3 slashes ///     -----Ursprüngliche Nachricht----- Von:Jonathan Wakely via Std-Proposals <std-proposals_at_[hidden]> Gesendet:Sa 22.03.2025 11:44 Betreff:Re: [std-proposals] Standardizing doc comments An:std-proposals_at_[hidden]; CC:Jonathan Wakely <cxx_at_[hidden]>;   On Sat, 22 Mar 2025 at 09:53, Simon Schröder via Std-Proposals <std-proposals_at_[hidden] <mailto:std-proposals_at_[hidden]> > wrote: I don’t fully agree with you, Thiago. C++ also does not have a reference compiler and still we write a standard to define the language. The same can apply for doc comments. Isn’t there also a committee for tooling? It could be in the interest of the tooling group to also unify tooling around documentation. This would require a unified syntax in the language.  No, it doesn't have to be in the C++ standard for any of the benefits to happen. The tools that consume those comments are not "C++ implementations" so are out of scope for the C++ standard. See the first sentence of the first clause of the standard: "This document specifies requirements for implementations of the C++ programming language."  Comments do not affect the behaviour of the program as defined by the abstract machine and the rules of the C++ standard.     However, this also has some major problems: 1) Syntax: it should not collide with existing doc comments because they might not follow the correct syntax for (to be) standardized tools. A different syntax to declare doc comments might make people hesitate to adopt the standardized syntax because it is unconventional. 2) Which doc syntax is the best? I took a quick glance at JavaDoc and there is some legacy syntax and a new syntax featuring markdown. The problem with Markdown is that it has too many different incompatible flavors. Which flavor should we use? Or should we use reStructuredText? I like the approach of Sphinx Doc, but it is currently very complicated to use with inline doc comments (you can use Doxygen to extract the doc comments and then feed that into Sphinx). Should we fall into the trap of JavaDoc and just use the current fad? (Is Markdown a fad? Will it go away eventually and be replaced by something else? How should C++ doc comments adapt to that?) I’d expect the C++ community to have to specify something that is future proof. This would be a battle of who can predict the future best. I would certainly support having a unified syntax for doc comments. But, I’d expect it to take a long time to write a specification that everybody agrees on. We have missed the train when Doxygen was the de facto standard. Other tools claim to do it better now. And certainly other tools look more modern by default.  These are problems that a standard *can* address, by picking a format and declaring all the others non-conforming (or by allowing all the competing formats). I don't think doing that belongs in the C++ standard.  A white paper from the tooling study group might be a reasonable delivery vehicle for it, but somebody would need to do the work, including getting buy-in from the existing vendors (who aren't necessarily involved with WG21 at present).   -- Std-Proposals mailing list Std-Proposals_at_[hidden] https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals -- Std-Proposals mailing list Std-Proposals_at_[hidden] https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals