Is it legal to use \\ in // C++ comment? (LaTeX equation in C++ comment)

user_2001017 0
Viewed 348

For documentation purpose I need to add some LaTeX equations in my C++ comments, by example:

//
// \begin{eqnarray*}
//   y_1 &=& x_1 \\
//   y_2 &=& x_2 
// \end{eqnarray*}
//
int main() {}

With clang++ (version 9.0.1-10) I can compile my code without problem:

clang++ -Wall prog.cpp

but with g++ (version 9.2.1)

g++ -Wall prog.cpp

I get this warning:

prog.cpp:3:1: warning: multi-line comment [-Wcomment]
    3 | //   y_1 &=& x_1 \\
      | ^

My question: which compiler is right? Can I legally use \\ inside C++ // comment?

clang++ language-lawyer g++ c++
5 Answers

Is it legal? Yes. Is it error prone? Yes. That's why you are getting a warning.

The C/C++ standard has one token above all (processed first): \

This token removes the line break. Consider the following code:

1.  // the below code is commented out \
2.  despite not having a comment at the beginning of the line
3.  
4.  // it's important to be careful because \\
5.  int not_compiled_code = 0;
6.  // the above code is not compiled.

Despite stackoverflow's syntax highlighting, lines 2 and 5 are not compiled.

In case you're wondering, the next tokens are // and /*.

// /* incomplete block comment
int compiled_code = 0;

/*
// this entire line isn't commented */ int compiled_code_2 = 0;

which compiler is right?

Both, because warnings are irrelevant to the standard. They compiled successfully and that's all that matters - they both conformed properly to the standard.

Admin1

Such comments are legal, but they could have unexpected effects, hence the warning. The next line after the one with the backslash at the end is a continuation of the comment, regardless of the // at the beginning. So this

// \\
Hey dude!
int main () {}

is a valid C++ program. And no, the backslash before the last one does not serve as an escape.

If you want to avoid the warning, put a LaTeX comment in the end of the line:

// y_1 &=& x_1 \\ % look ma, no warning

Note that a simple space between the backslash and the newline doesn't necessarily fix the problem. GCC documentation says:

If there is white space between a backslash and the end of a line, that is still a continued line. However, as this is usually the result of an editing mistake, and many compilers will not accept it as a continued line, GCC will warn you about it.

user_7758060

According to cpp reference

C++-style comments tell the compiler to ignore all content between // and a new line.

So your comment should be legal. Notice that g++ is only giving a warning, not an error.

g++ is warning about the escaped newline

Warn whenever a comment-start sequence ‘/’ appears in a ‘/’ comment, or whenever a backslash-newline appears in a ‘//’ comment. This warning is enabled by -Wall

user_27276320

which compiler is right?

Both. The warning is not about "legal usage of \" the warning is about multiline comment.

In C a \ character on the end of the line means to ignore the newline. So the two lines:

// blabla\
abcabc

and:

// blabalabcbc

Are exactly equivalent. The double backslash \\ is just a backslash \ that is escaped by \, so it is first substituted by a backslash, then preprocessor detects backslashes followed by a newline and deletes newlines. That's why it's dangerous.

int a = 1;
// increase a \\
a++;
printf("%d\n", a); // will print `1`
user_90727530

A practical solution is to use /* multi-line comments. So code

/***
 \begin{eqnarray*}
   y_1 &=& x_1 \\
   y_2 &=& x_2 
 \end{eqnarray*}
***/

You should be interested by literate programming techniques, and by tools like Doxygen.

My recommendation is to try Nuweb (at least if you code on Linux), in particular for your public (and LaTeX documented) header files. You'll code a Nuweb source file (some *.nw file) which would generate LaTeX on one hand, and C code on another (e.g. some header file).

Be aware that using literate programming techniques takes a lot of time. My personal but limited experience is that they are worth using more on public header files than on implementation details and entire translation units.

Of course, you need to learn more about build automation tools (such as GNU make or ninja) and configure them explicitly for running your nuweb or doxygen executable appropriately.

user_8411080
Related