The commands in this table insert, kill and align comments:
comment-indent-new-line). See Multi-Line Comments.
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, M-; either adds or removes comment
delimiters on each line of the region. See Mark. If every line in
the region is a comment, it removes comment delimiters from each;
otherwise, it adds comment delimiters to each. You can also use the
explicitly comment or uncomment the text in the region
(see Multi-Line Comments). If you supply a prefix argument to
M-; when a region is active, that specifies how many comment
delimiters to add or how many to delete.
If the region is not active, M-; inserts a new comment if
there is no comment already on the line. The new comment is normally
aligned at a specific column called the comment column; if the
text of the line extends past the comment column, M-; aligns the
comment start string to a suitable boundary (usually, at least one
space is inserted). The comment begins with the string Emacs thinks
comments should start with (the value of
below). Emacs places point after that string, so you can insert the
text of the comment right away. If the major mode has specified a
string to terminate comments, M-; inserts that string after
point, to keep the syntax valid.
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 it. (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 text inside the comment.
C-u M-; kills any comment on the current line, along with the whitespace before it. To reinsert the comment on another line, move to the end of that line, do C-y, and then do M-; to realign it.
Note that C-u M-; is not a distinct key; it is M-;
comment-dwim) with a prefix argument. That command is
programmed so that when it receives a prefix argument it calls
comment-kill is a valid command
in its own right, and you can bind it directly to a key if you wish.
Some major modes have special rules for aligning certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin and are often used for sectioning purposes. Emacs understands these conventions by indenting a double-semicolon comment using <TAB>, and by not changing the indentation of a triple-semicolon comment at all.
;; This function is just an example. ;;; Here either two or three semicolons are appropriate. (defun foo (x) ;;; And now, the first part of the function: ;; The following line adds one. (1+ x)) ; This line adds one.
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