Stehsaer wrote: > Showing the `Details:` paragraph/section like in your example is intended. > > The purpose is to create an own section for the detailed description, like > for `Parameters` and `Return` etc. And in fact, this section is not empty. It > "contains" the note command in your example. > > In your example case the ruler after the `Details:` section heading is > confusing maybe. But this ruler is actually part of the `@note` command. I > added this ruler to try to emphasize the `@note` even more, like the markdown > alerts would. > > But we could also remove these rulers for the `note`, `warning` highlights to > not separate it too much from the rest of the text. > > Also note that the **sections** `Parameters`, `Return`, `Details` etc. are > different than the **highlighting** of the `note` and `warning` commands. The > highlighting is "inline" and can be used multiple times, whereas the sections > are structural adaptions and unique.
This totally makes sense. Shall we make the `Details:` text a header (H5 or H6? I'm not quite sure), in order to make it bigger and separates more from other small headers like `Note:`? --- And also, another case with unexpected behavior was found: ```cpp /// /// @brief Some brief /// /// @param some_param Some description /// @retval 0 on success /// @retval 1 Kitty asleep /// int worker_thread(const std::string& some_param); ``` <img width="607" height="404" alt="image" src="https://github.com/user-attachments/assets/b09c9405-ca36-4a9e-9d78-a993c48642b7"; /> Literally there's nothing under the `Details:` header, is there any empty line that is mistakenly parsed as a part of detail? Removing the trailing empty comment still yields the `Details:` header followed with empty content. Here are some further tests on this issue: #### Simple comment with `@brief` ```cpp /// /// @brief Some brief /// int worker_thread(const std::string& some_param); ``` <img width="600" height="344" alt="image" src="https://github.com/user-attachments/assets/bc38f12b-2c7b-4d32-b269-9ae305bd98b0"; /> #### Simple comment without `@brief` ```cpp /// /// Some brief /// int worker_thread(const std::string& some_param); ``` <img width="606" height="300" alt="image" src="https://github.com/user-attachments/assets/27f0daf3-ca05-42e9-b32b-2d174d3722b6"; /> #### Original case without `@brief` ```cpp /// /// Some brief /// /// @param some_param Some description /// @retval 0 on success /// @retval 1 Kitty asleep /// int worker_thread(const std::string& some_param); ``` <img width="608" height="407" alt="image" src="https://github.com/user-attachments/assets/c194394e-4800-4ce4-8b2b-74d169402174"; /> https://github.com/llvm/llvm-project/pull/156365 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
