From aefc30753ad36bd3059674d7765aacb955a72bd9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 2 Dec 2025 17:19:27 +0000 Subject: [PATCH 1/8] feat: migrate c/comment from cppref [#44] --- src/content/docs/c/comment.mdx | 157 +++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 src/content/docs/c/comment.mdx diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx new file mode 100644 index 00000000..36c45192 --- /dev/null +++ b/src/content/docs/c/comment.mdx @@ -0,0 +1,157 @@ +--- +title: "Comments" +description: Auto‑generated from cppreference +--- + +import { Desc, DescList, DocLink, Revision } from '@components/index'; + +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. + +### Syntax + +(1) `/*` comment `*/` +(2) `//` comment (since C99) + +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 translation phase 3 by replacing each comment with a single whitespace character. + +### C-style + +C-style comments are usually used to comment large blocks of text or small fragments of code; however, they can be used to comment single lines. To insert text as a C-style comment, simply surround the text with `/*` and `*/`. C-style comments tell the compiler to ignore all content between `/*` and `*/`. 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. + +Except within a character constant, a string literal, or a comment, the characters `/*` introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters `*/` that terminate the comment. C-style comments cannot be nested. + + + +### C++-style + +C++-style comments are usually used to comment single lines of text or code; however, they can be placed together to form multi-line comments. To insert text as a C++-style comment, simply precede the text with `//` and follow the text with the new line character. C++-style comments tell the compiler to ignore all content between `//` and a new line. + +Except within a character constant, a string literal, or a comment, the characters `//` introduce a comment that includes all multibyte characters up to, but not including, the next new-line character. The contents of such a comment are examined only to identify multibyte characters and to find the new-line character that terminates the comment. C++-style comments can be nested: + +```c +// y = f(x); // invoke algorithm +``` + +A C-style comment may appear within a C++-style comment: + +```c +// y = f(x); /* invoke algorithm */ +``` + +A C++-style comment may appear within a C-style comment; this is a mechanism for excluding a small block of source code: + +```c +/* + y = f(x); // invoke algorithms + z = g(x); +*/ +``` + + + +### Notes + +Because comments are removed 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. + +```c +/* An attempt to use a macro to form a comment. */ +/* But, a space replaces characters "//". */ +#ifndef DEBUG + #define PRINTF // +#else + #define PRINTF printf +#endif +... +PRINTF("Error in file%s at line%i\n", __FILE__, __LINE__); +``` + +Besides commenting out, other mechanisms used for source code exclusion are: + +```c +#if 0 + puts("this will not be compiled"); + /* no conflict with C-style comments */ + // no conflict with C++-style comments +#endif +``` + +and + +```c +if(0) { + puts("this will be compiled but not be executed"); + /* no conflict with C-style comments */ + // no conflict with C++-style comments +} +``` + +The introduction of // comments in C99 was a breaking change in some rare circumstances: + +```c +a = b //*divisor:*/ c ++ d; /* C89 compiles a = b / c + d; + C99 compiles a = b + d; */ +``` + +### Example + +```cpp +#include +/* +C-style comments can contain +multiple lines. +*/ + +/* Or, just one line. */ + +// C++-style comments can comment one line. + +// Or, they can +// be strung together. + +int main(void) +{ + // The below code won't be run + // puts("Hello"); + + // The below code will be run + puts("World"); + + // A note regarding backslash + newline. + // Despite belonging to translation phase 2 (vs phase 3 for comments), + // '\' still determines which portion of the source code is considered + // as 'comments': + // This comment will be promoted to the next line \ + puts("Won't be run"); // may issue a warning "multi-line comment" + puts("Hello, again"); +} +``` + +Output: + +```text +World +Hello, again +``` + +### References + +* C17 standard (ISO/IEC 9899:2018): + * 6.4.9 Comments (p: 54) +* C11 standard (ISO/IEC 9899:2011): + * 6.4.9 Comments (p: 75) +* C99 standard (ISO/IEC 9899:1999): + * 6.4.9 Comments (p: 66) +* C89/C90 standard (ISO/IEC 9899:1990): + * 3.1.9 Comments + +### See also + + + + C++ documentation for Comments + + \ No newline at end of file From 4445122f85f186453ed8b2113153aa2be567a74f Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:25:20 +0800 Subject: [PATCH 2/8] fix: style --- src/content/docs/c/comment.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index 36c45192..d84c84c3 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -3,14 +3,14 @@ title: "Comments" description: Auto‑generated from cppreference --- -import { Desc, DescList, DocLink, Revision } from '@components/index'; +import { Desc, DescList, DocLink, Revision, RevisionBlock } from '@components/index'; 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. ### Syntax -(1) `/*` comment `*/` -(2) `//` comment (since C99) +* (1) `/*` comment `*/` +* (2) `//` comment (since C99) 1) Often known as "C-style" or "multi-line" comments. 2) Often known as "C++-style" or "single-line" comments. @@ -23,7 +23,7 @@ C-style comments are usually used to comment large blocks of text or small fragm Except within a character constant, a string literal, or a comment, the characters `/*` introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters `*/` that terminate the comment. C-style comments cannot be nested. - + ### C++-style @@ -154,4 +154,4 @@ Hello, again C++ documentation for Comments - \ No newline at end of file + From ee81d8e8c9623b4778b6e418066f0116e2ede6bd Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:26:56 +0800 Subject: [PATCH 3/8] Update notes on C-style comments and preprocessor Clarified that comments are removed before preprocessor stage. --- src/content/docs/c/comment.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index d84c84c3..1140dc06 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -50,7 +50,7 @@ A C++-style comment may appear within a C-style comment; this is a mechanism for */ ``` - + ### Notes From 621b4cbaf737bb3f8f285a66911cb3ad9c9d5d27 Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:29:02 +0800 Subject: [PATCH 4/8] Update comment.mdx --- src/content/docs/c/comment.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index 1140dc06..45091cc7 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -9,8 +9,8 @@ Comments serve as a sort of in-code documentation. When inserted into a program, ### Syntax -* (1) `/*` comment `*/` -* (2) `//` comment (since C99) +* (1) `/*` _comment_ `*/` +* (2) `//` _comment_   1) Often known as "C-style" or "multi-line" comments. 2) Often known as "C++-style" or "single-line" comments. From 64147341b144fc0c1c6ea10bc26815d04a068454 Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:30:23 +0800 Subject: [PATCH 5/8] Fix formatting of C comment syntax example --- src/content/docs/c/comment.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index 45091cc7..0174ce78 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -10,7 +10,7 @@ Comments serve as a sort of in-code documentation. When inserted into a program, ### Syntax * (1) `/*` _comment_ `*/` -* (2) `//` _comment_   +* (2) `//` _comment_   1) Often known as "C-style" or "multi-line" comments. 2) Often known as "C++-style" or "single-line" comments. From 1b548b2ad18627ddd5d3a6ea644bf623fe6d37d1 Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:32:11 +0800 Subject: [PATCH 6/8] Fix syntax formatting for C comments in documentation --- src/content/docs/c/comment.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index 0174ce78..6d63f9c5 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -10,7 +10,8 @@ Comments serve as a sort of in-code documentation. When inserted into a program, ### Syntax * (1) `/*` _comment_ `*/` -* (2) `//` _comment_   + +* (2) `//` _comment_   1) Often known as "C-style" or "multi-line" comments. 2) Often known as "C++-style" or "single-line" comments. From 7e56b71053c9c315553d2a58cbc9716562fae0a5 Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:33:24 +0800 Subject: [PATCH 7/8] Fix comment syntax formatting in C documentation --- src/content/docs/c/comment.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index 6d63f9c5..849d6ae7 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -10,8 +10,7 @@ Comments serve as a sort of in-code documentation. When inserted into a program, ### Syntax * (1) `/*` _comment_ `*/` - -* (2) `//` _comment_   +* (2) `//` _comment_   1) Often known as "C-style" or "multi-line" comments. 2) Often known as "C++-style" or "single-line" comments. From df877c7699400dc238482720f3720ff61f166b19 Mon Sep 17 00:00:00 2001 From: MicroBlock <66859419+std-microblock@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:33:49 +0800 Subject: [PATCH 8/8] Remove auto-generated description from comment.mdx --- src/content/docs/c/comment.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/c/comment.mdx b/src/content/docs/c/comment.mdx index 849d6ae7..e18b4062 100644 --- a/src/content/docs/c/comment.mdx +++ b/src/content/docs/c/comment.mdx @@ -1,6 +1,5 @@ --- title: "Comments" -description: Auto‑generated from cppreference --- import { Desc, DescList, DocLink, Revision, RevisionBlock } from '@components/index';