Comments Multi-Line Comments

20.7.1: Comment Commands

The comment commands insert, kill and align comments.

The command that creates a comment is M-; (indent-for-comment). If there is no comment already on the line, a new comment is created, aligned at a specific column called the comment column. The comment is created by inserting the string Emacs thinks comments should start with (the value of comment-start; see below). Point is left after that string. If the text of the line extends past the comment column, then the indentation is done to a suitable boundary (usually, at least one space is inserted). If the major mode has specified a string to terminate comments, that is inserted after point, to keep the syntax valid.

M-; can also be used to align an existing comment. If a line already contains the string that starts comments, then M-; just moves point after it and reindents it to the conventional place. Exception: comments starting in column 0 are not moved.

Some major modes have special rules for indenting 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. 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.

In C code, a comment preceded on its line by nothing but whitespace is indented like a line of code.

Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the comment.

C-u - C-x ; (kill-comment) kills the comment on the current line, if there is one. The indentation before the start of the comment is killed as well. If there does not appear to be a comment in the line, nothing is done. 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 - C-x ; is not a distinct key; it is C-x ; (set-comment-column) with a negative argument. That command is programmed so that when it receives a negative argument it calls kill-comment. However, kill-comment is a valid command which you could bind directly to a key if you wanted to.

Comments

Multi-Line Comments