[clang-tools-extra] [clang-doc] Fix file header style (PR #190437)

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang-tools-extra

Author: Paul Kirth (ilovepi)

<details>
<summary>Changes</summary>

Since we're fixing headers, we can also improve the file documentation
to follow the llvm coding standard.

---
Full diff: https://github.com/llvm/llvm-project/pull/190437.diff


6 Files Affected:

- (modified) clang-tools-extra/clang-doc/JSONGenerator.cpp (+16) 
- (modified) clang-tools-extra/clang-doc/MDMustacheGenerator.cpp (+4-1) 
- (modified) clang-tools-extra/clang-doc/support/File.cpp (+6) 
- (modified) clang-tools-extra/clang-doc/support/File.h (+6) 
- (modified) clang-tools-extra/clang-doc/support/Utils.cpp (+6) 
- (modified) clang-tools-extra/clang-doc/support/Utils.h (+8) 


``````````diff
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 8db7eaafcfb30..86c8a9afeddcf 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -1,3 +1,19 @@
+//===-- JSONGenerator.cpp - JSON Generator ----------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the implementation of the JSONGenerator, which serializes
+/// the clang-doc internal representation (Info structures) into JSON format.
+/// It handles the mapping of C++ constructs like namespaces, records,
+/// functions, and enums to their JSON equivalents, enabling downstream tools
+/// to consume the structured documentation data.
+///
+//===----------------------------------------------------------------------===//
 #include "Generators.h"
 #include "clang/Basic/Specifiers.h"
 #include "llvm/ADT/ArrayRef.h"
diff --git a/clang-tools-extra/clang-doc/MDMustacheGenerator.cpp b/clang-tools-extra/clang-doc/MDMustacheGenerator.cpp
index a8142c7a97f18..d2ae948a535db 100644
--- a/clang-tools-extra/clang-doc/MDMustacheGenerator.cpp
+++ b/clang-tools-extra/clang-doc/MDMustacheGenerator.cpp
@@ -7,7 +7,10 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// Contains the Markdown generator using Mustache template files.
+/// This file contains the implementation of the MDMustacheGenerator, which
+/// generates documentation in Markdown format using Mustache templates. It
+/// defines how the structured data in Info objects is mapped to template
+/// tags to produce readable markdown documents.
 ///
 //===----------------------------------------------------------------------===//
 
diff --git a/clang-tools-extra/clang-doc/support/File.cpp b/clang-tools-extra/clang-doc/support/File.cpp
index 95769bec6a209..89ca6d8c5f4af 100644
--- a/clang-tools-extra/clang-doc/support/File.cpp
+++ b/clang-tools-extra/clang-doc/support/File.cpp
@@ -5,6 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the implementations of file I/O utility functions
+/// used in clang-doc.
+///
+//===----------------------------------------------------------------------===//
 #include "File.h"
 #include "llvm/Support/FileSystem.h"
 #include "llvm/Support/Path.h"
diff --git a/clang-tools-extra/clang-doc/support/File.h b/clang-tools-extra/clang-doc/support/File.h
index bab988f0e5c86..dc8ede07a635f 100644
--- a/clang-tools-extra/clang-doc/support/File.h
+++ b/clang-tools-extra/clang-doc/support/File.h
@@ -5,6 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains file I/O utility functions used in clang-doc,
+/// such as creating directories and writing output files.
+///
+//===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
 
diff --git a/clang-tools-extra/clang-doc/support/Utils.cpp b/clang-tools-extra/clang-doc/support/Utils.cpp
index 0691db06a06ca..c3992db86bff0 100644
--- a/clang-tools-extra/clang-doc/support/Utils.cpp
+++ b/clang-tools-extra/clang-doc/support/Utils.cpp
@@ -5,6 +5,12 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains the implementations of general utility functions used
+/// across the clang-doc tool.
+///
+//===----------------------------------------------------------------------===//
 
 #include "Utils.h"
 #include "llvm/ADT/SmallString.h"
diff --git a/clang-tools-extra/clang-doc/support/Utils.h b/clang-tools-extra/clang-doc/support/Utils.h
index d862f53c55b9a..1d2e547f41a72 100644
--- a/clang-tools-extra/clang-doc/support/Utils.h
+++ b/clang-tools-extra/clang-doc/support/Utils.h
@@ -5,6 +5,14 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains general utility functions and helpers used across the
+/// clang-doc tool, including string manipulation and path handling. It
+/// provides lightweight utilities that do not depend on the core clang-doc
+/// data model.
+///
+//===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_FILE_H
 

``````````

</details>


https://github.com/llvm/llvm-project/pull/190437