From d6e09cb5a456b2e63617e51980f46bc39bb04eff Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 2 Dec 2025 10:09:01 +0000
Subject: [PATCH 1/2] Migrate https://en.cppreference.com/w/cpp/comments.html

---
 src/content/docs/cpp/comments.mdx | 106 ++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 src/content/docs/cpp/comments.mdx

diff --git a/src/content/docs/cpp/comments.mdx b/src/content/docs/cpp/comments.mdx
new file mode 100644
index 00000000..0c74e6f8
--- /dev/null
+++ b/src/content/docs/cpp/comments.mdx
@@ -0,0 +1,106 @@
+---
+title: Comments
+description: Auto‑generated from cppreference
+---
+
+import { Desc, DescList, DocLink } from '@components/index';
+
+# Comments
+
+Comments serve as a sort of in-code documentation. When inserted into a program, they are effectively ignored by the compiler; they are solely intended to be used as notes by the humans that read source code. Although specific documentation is not part of the C++ standard, several utilities exist that parse comments with different documentation formats.
+
+## Syntax
+
+```
+/* comment */
+```
+
+(1)
+```
+// comment
+```
+
+(2)
+
+1) Often known as "C-style" or "multi-line" comments.
+2) Often known as "C++-style" or "single-line" comments.
+
+All comments are removed from the program at <DocLink src="/cpp/language/translation_phases">translation phase 3</DocLink> by replacing each comment with a single whitespace character.
+
+## C-style
+
+C-style comments are usually used to comment large blocks of text, however, they can be used to comment single lines. To insert a C-style comment, simply surround text with `/*` and `*/`; this will cause the contents of the comment to be ignored by the compiler. Although it is not part of the C++ standard, `/**` and `*/` are often used to indicate documentation blocks; this is legal because the second asterisk is simply treated as part of the comment. C-style comments cannot be nested.
+
+## C++-style
+
+C++-style comments are usually used to comment single lines, however, multiple C++-style comments can be placed together to form multi-line comments. C++-style comments tell the compiler to ignore all content between `//` and a new line.
+
+## Notes
+
+Because comments <DocLink src="/cpp/language/translation_phases">are removed</DocLink> before the preprocessor stage, a macro cannot be used to form a comment and an unterminated C-style comment doesn't spill over from an #include'd file.
+
+Besides commenting out, other mechanisms used for source code exclusion are
+
+```cpp
+#if 0
+    std::cout << "this will not be executed or even compiled\n";
+#endif
+```
+
+and
+
+```cpp
+if (false)
+{
+    std::cout << "this will not be executed\n";
+}
+```
+
+## Example
+
+```cpp
+#include <iostream>
+
+/* C-style comments can contain
+multiple lines */
+/* or just one */
+
+/**************
+ *  you can insert any *, but
+ *  you can't make comments nested
+ */
+
+// C++-style comments can comment one line
+
+// or, they can
+// be strung together
+
+int main()
+{
+    // comments are removed before preprocessing,
+    // so ABC is "1", not "1//2134", and "1 hello world"
+    // will be printed
+#define ABC 1//2134
+    std::cout << ABC << " hello world\n";
+
+    // The below code won't be run
+    // return 1;
+
+    // The below code will be run
+    return 0;
+}
+```
+
+Output:
+
+```text
+1 hello world
+```
+
+## See also
+
+<DescList>
+<Desc>
+<DocLink slot="item" src="/c/comment">C documentation</DocLink> for <span>comment</span>
+</Desc>
+</DescList>
\ No newline at end of file

From 2528ec677f6c88a4f6079c67985d368fccae723a Mon Sep 17 00:00:00 2001
From: MicroBlock <66859419+std-microblock@users.noreply.github.com>
Date: Tue, 2 Dec 2025 18:19:29 +0800
Subject: [PATCH 2/2] Refactor comments section for clarity and formatting

Removed redundant numbering and improved comment syntax formatting.
---
 src/content/docs/cpp/comments.mdx | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/src/content/docs/cpp/comments.mdx b/src/content/docs/cpp/comments.mdx
index 0c74e6f8..e843c693 100644
--- a/src/content/docs/cpp/comments.mdx
+++ b/src/content/docs/cpp/comments.mdx
@@ -11,20 +11,18 @@ Comments serve as a sort of in-code documentation. When inserted into a program,
 
 ## Syntax
 
+#### Block Comment
+Often known as "C-style" or "multi-line" comments.
+
 ```
 /* comment */
 ```
-
-(1)
+#### Single-line Comment
+Often known as "C++-style" or "single-line" comments.
 ```
 // comment
 ```
 
-(2)
-
-1) Often known as "C-style" or "multi-line" comments.
-2) Often known as "C++-style" or "single-line" comments.
-
 All comments are removed from the program at <DocLink src="/cpp/language/translation_phases">translation phase 3</DocLink> by replacing each comment with a single whitespace character.
 
 ## C-style
@@ -103,4 +101,4 @@ Output:
 <Desc>
 <DocLink slot="item" src="/c/comment">C documentation</DocLink> for <span>comment</span>
 </Desc>
-</DescList>
\ No newline at end of file
+</DescList>