26.5.1 Comment Commands
The following commands operate on comments:
Insert or realign comment on current line; if the region is active,
comment or uncomment the region instead (
- C-x C-;
Comment or uncomment the current line (
comment-line). If the
region is active, comment or uncomment the lines in the region
- C-u M-;
Kill comment on current line (
- C-x ;
Set comment column (
Like RET followed by inserting and aligning a comment
comment-indent-new-line). See Multiple Lines of Comments.
- M-x comment-region
- C-c C-c (in C-like modes)
Add comment delimiters to all the lines in the region.
The command to create or align a comment is M-;
comment-dwim). The word “dwim” is an acronym for “Do What
I Mean”; it indicates that this command can be used for many
different jobs relating to comments, depending on the situation where
you use it.
When a region is active (see The Mark and the Region), M-; either adds
comment delimiters to the region, or removes them. If every line in
the region is already a comment, it uncomments each of those lines
by removing their comment delimiters. Otherwise, it adds comment
delimiters to enclose the text in the region.
If you supply a prefix argument to M-; when a region is
active, that specifies the number of comment delimiters to add or
delete. A positive argument n adds n delimiters, while a
negative argument -n removes n delimiters.
If the region is not active, and there is no existing comment on the
current line, M-; adds a new comment to the current line. If
the line is blank (i.e., empty or containing only whitespace
characters), the comment is indented to the same position where
TAB would indent to (see Basic Program Indentation Commands). If the line
is non-blank, the comment is placed after the last non-whitespace
character on the line. Emacs tries to fit the comment between the
columns specified by the variables
comment-fill-column (see Options Controlling Comments), if
possible. Otherwise, it will choose some other suitable position,
usually separated from the non-comment text by at least one space. In
each case, Emacs places point after the comment’s starting delimiter,
so that you can start typing the comment text right away.
You can also use M-; to align an existing comment. If a line
already contains the comment-start string, M-; realigns it to
the conventional alignment and moves point after the comment’s
starting delimiter. As an exception, comments starting in column 0
are not moved. Even when an existing comment is properly aligned,
M-; is still useful for moving directly to the start of the
C-x C-; (
comment-line) comments or uncomments complete
lines. When a region is active (see The Mark and the Region), C-x C-; either
comments or uncomments the lines in the region. If the region is not
active, this command comments or uncomments the line point is on.
With a positive prefix argument n, it operates on n lines
starting with the current one; with a negative argument
-n, it affects n preceding lines. After invoking
this command with a negative argument, successive invocations with a
positive argument will operate on preceding lines as if the argument
C-u M-; (
comment-dwim with a prefix argument) kills any
comment on the current line, along with the whitespace before it.
Since the comment is saved to the kill ring, you can reinsert it on
another line by moving to the end of that line, doing C-y, and
then M-; to realign the comment. You can achieve the same
effect as C-u M-; by typing M-x comment-kill
comment-dwim actually calls
comment-kill as a
subroutine when it is given a prefix argument).
The command M-x comment-region is equivalent to calling
M-; on an active region, except that it always acts on the
region, even if the mark is inactive. In C mode and related modes,
this command is bound to C-c C-c. The command M-x
uncomment-region uncomments each line in the region; a numeric prefix
argument specifies the number of comment delimiters to remove
(negative arguments specify the number of comment delimiters to add).
For C-like modes, you can configure the exact effect of M-; by
setting the variables
c-indent-comments-syntactically-p. For example, on a line
ending in a closing brace, M-; puts the comment one space after
the brace rather than at
comment-column. For full details see
Comment Commands in The CC Mode Manual.