Emacs: Comment Commands

Comment Commands
----------------

  The comment commands in this table insert, kill and align comments.
They are described in this section and following sections.

`M-;'
    Insert or realign comment on current line; alternatively, comment
    or uncomment the region (`comment-dwim').

`C-u M-;'
    Kill comment on current line (`comment-kill').

`C-x ;'
    Set comment column (`comment-set-column').

`C-M-j'
    Like  followed by inserting and aligning a comment
    (`comment-indent-new-line').

`M-x comment-region'
    Add or remove comment delimiters on 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.

  If there is no comment already on the line, `M-;' inserts a new
comment, aligned at a specific column called the "comment column".  The
new comment begins with the string Emacs thinks comments should start
with (the value of `comment-start'; see below).  Point is 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 too, to keep the syntax valid.

  If the text of the line extends past the comment column, then the
comment start string is indented to a suitable boundary (usually, at
least one space is inserted).

  You can also use `M-;' to align an existing comment.  If a line
already contains the comment-start string, `M-;' reindents 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'.
However, `comment-kill' is a valid command in its own right, and you
can bind it directly to a key if you wish.

  `M-;' does two other jobs when used with an active region in
Transient Mark mode (Note: Transient Mark).  Then it either adds or
removes comment delimiters on each line of the region.  (If every line
is a comment, it removes comment delimiters from each; otherwise, it
adds comment delimiters to each.)  If you are not using Transient Mark
mode, then you should use the commands `comment-region' and
`uncomment-region' to do these jobs (Note: Multi-Line Comments).  A
prefix argument used in these circumstances specifies how many comment
delimiters to add or how many to delete.

  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 ,
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.