(lemacs.info)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').

   The command that creates a comment is `Meta-;'
(`indent-for-comment').  If there is no comment already on the line, a
new comment is created and aligned at a specific column called the
"comment column".  Emacs creates the comment by inserting the string at
the value of `comment-start'; see below.  Point is left after that
string.  If the text of the line extends past the comment column,
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 string is inserted after point, to keep the syntax valid.

   You can also use `Meta-;' to align an existing comment.  If a line
already contains the string that starts comments, `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 happens.  To reinsert the comment on another line, move
to the end of that line, type first `C-y', and then `M-;' to realign
the comment.  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 to call `kill-comment' when called with a negative argument.
However, `kill-comment' is a valid command which you could bind
directly to a key if you wanted to.

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

   If you are typing a comment and want to continue it on another line,
use the command `Meta-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.  If
Auto Fill mode is on and you go past the fill column while typing, the
comment is continued in just this fashion.  If point is not at the end
of the line when you type `M-LFD', 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 explicitly set it to a number.  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 calls `Meta-;' 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.

   `comment-column' is a per-buffer variable; altering the variable
affects only the current buffer.  You can also change the default value.
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 and will follow the text you will insert into the comment.
In C mode, `comment-start' has the value `"/* "' and `comment-end' has
the value `" */"'.

   `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 `M-LFD'
terminates the comment on the starting line and starts a new comment on
the new following line.  If `comment-multi-line' is not `nil', then
`M-LFD' sets up the new following line 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 are legal, the value you choose
for this variable is a matter of taste.

   The variable `comment-indent-hook' should contain a function that is
called to compute the indentation for a newly inserted comment or for
aligning an existing comment.  Major modes set this variable
differently.  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.  The function should return the column in
which the comment ought to start.  For example, in Lisp mode, the
indent hook function bases its decision on the number of semicolons
that begin an existing comment and on the code in the preceding lines.


automatically generated by info2www