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

[Paul Kirth via cfe-commits]

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

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

>From 8e791570d9d73c6d083d4e718d26d3ac8cb3dc34 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulkirth at google.com>
Date: Sat, 4 Apr 2026 00:36:27 +0000
Subject: [PATCH] [clang-doc] Fix file header style

Since we're fixing headers, we can also improve the file documentation
to follow the llvm coding standard.
---
 clang-tools-extra/clang-doc/JSONGenerator.cpp    | 16 ++++++++++++++++
 .../clang-doc/MDMustacheGenerator.cpp            |  5 ++++-
 clang-tools-extra/clang-doc/support/File.cpp     |  6 ++++++
 clang-tools-extra/clang-doc/support/File.h       |  6 ++++++
 clang-tools-extra/clang-doc/support/Utils.cpp    |  6 ++++++
 clang-tools-extra/clang-doc/support/Utils.h      |  8 ++++++++
 6 files changed, 46 insertions(+), 1 deletion(-)

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