(emacs)Comments


Next: Balanced Editing Prev: Matching Up: Programs

Manipulating Comments
=====================

   The comment commands insert, kill and align comments.

`M-;'
     Insert or align comment (`indent-for-comment').

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

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

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

`M-x comment-region'
     Add or remove comment delimiters on all the lines in the region.

   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 re-indents 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.

   The `M-x comment-region' command adds comment delimiters to the
lines that start in the region, thus commenting them out.  With a
negative argument, it does the opposite--it deletes comment delimiters
from the lines in the region.

   With a positive argument, `comment-region' adds comment delimiters
and duplicates the last character of the comment start sequence as many
times as the argument specifies.  Thus, in Lisp mode, `C-u 2 M-x
comment-region' adds `;;' to each line.

   Duplicating the comment delimiter is a way of calling attention to
the comment.  It can also affect how the comment is indented.  In Lisp,
for proper indentation, you should use an argument of two, if between
defuns, and three, if within a defun.

Multiple Lines of Comments
--------------------------

   If you are typing a comment and find that you wish to continue it on
another line, you can use the command `M-LFD'
(`indent-new-comment-line'), which terminates the comment you are
typing, creates a new blank line afterward, and begins a new comment
indented under the old one.  When Auto Fill mode is on, going past the
fill column while typing a comment causes the comment to be continued in
just this fashion.  If point is not at the end of the line when `M-LFD'
is typed, the text on the rest of the line becomes part of the new
comment line.

Options Controlling Comments
----------------------------

   The comment column is stored in the variable `comment-column'.  You
can set it to a number explicitly.  Alternatively, the command `C-x ;'
(`set-comment-column') sets the comment column to the column point is
at.  `C-u C-x ;' sets the comment column to match the last comment
before point in the buffer, and then does a `M-;' to align the current
line's comment under the previous one.  Note that `C-u - C-x ;' runs
the function `kill-comment' as described above.

   The variable `comment-column' is per-buffer: setting the variable in
the normal fashion affects only the current buffer, but there is a
default value which you can change with `setq-default'.  *Note
Locals::.  Many major modes initialize this variable for the current
buffer.

   The comment commands recognize comments based on the regular
expression that is the value of the variable `comment-start-skip'.
This regexp should not match the null string.  It may match more than
the comment starting delimiter in the strictest sense of the word; for
example, in C mode the value of the variable is `"/\\*+ *"', which
matches extra stars and spaces after the `/*' itself.  (Note that `\\'
is needed in Lisp syntax to include a `\' in the string, which is needed
to deny the first star its special meaning in regexp syntax.  *Note
Regexps::.)

   When a comment command makes a new comment, it inserts the value of
`comment-start' to begin it.  The value of `comment-end' is inserted
after point, so that it will follow the text that you will insert into
the comment.  In C mode, `comment-start' has the value `"/* "' and
`comment-end' has the value `" */"'.

   The variable `comment-multi-line' controls how `M-LFD'
(`indent-new-comment-line') behaves when used inside a comment.  If
`comment-multi-line' is `nil', as it normally is, then the comment on
the starting line is terminated and a new comment is started on the new
following line.  If `comment-multi-line' is not `nil', then the new
following line is set up as part of the same comment that was found on
the starting line.  This is done by not inserting a terminator on the
old line, and not inserting a starter on the new line.  In languages
where multi-line comments work, the choice of value for this variable
is a matter of taste.

   The variable `comment-indent-function' should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment.  It is set differently by
various major modes.  The function is called with no arguments, but with
point at the beginning of the comment, or at the end of a line if a new
comment is to be inserted.  It should return the column in which the
comment ought to start.  For example, in Lisp mode, the indent hook
function bases its decision on how many semicolons begin an existing
comment, and on the code in the preceding lines.


automatically generated by info2www