Cleanup: move public doc-strings into headers for 'blenkernel'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 6 insertions, 1 deletions

diff --git a/source/blender/blenkernel/BKE_report.h b/source/blender/blenkernel/BKE_report.h
index ec2e8d0f875..8b585fd0167 100644
--- a/source/blender/blenkernel/BKE_report.h
+++ b/source/blender/blenkernel/BKE_report.h
@@ -35,9 +35,14 @@ extern "C" {
  * These functions also accept NULL in case no error reporting
  * is needed. */
 
-/* report structures are stored in DNA */
+/* Report structures are stored in DNA. */
 
 void BKE_reports_init(ReportList *reports, int flag);
+/**
+ * Only frees the list \a reports.
+ * To make displayed reports disappear, either remove window-manager reports
+ * (#wmWindowManager.reports, or #CTX_wm_reports()), or use #WM_report_banners_cancel().
+ */
 void BKE_reports_clear(ReportList *reports);
 
 void BKE_report(ReportList *reports, eReportType type, const char *message);