mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-14 09:39:42 +00:00
Amend several doc strings and comments.
This commit is contained in:
Alan Mackenzie
parent
17abdd4783
commit
a85fd6da69
@ -11,6 +11,8 @@
|
||||
* progmodes/cc-cmds.el (c-indent-region): (c-indent-region): Fix
|
||||
previous patch so that the function works on one-line macros.
|
||||
|
||||
* progmodes/cc-engine.el: Amend several doc strings and comments.
|
||||
|
||||
2008-10-13 Dan Nicolaescu <dann@ics.uci.edu>
|
||||
|
||||
* vc-hooks.el (vc-stay-local): Add a new choice and default to it.
|
||||
@ -221,8 +223,6 @@
|
||||
|
||||
2008-10-07 Alan Mackenzie <acm@muc.de>
|
||||
|
||||
* progmodes/cc-engine.el: Amend several doc strings and comments.
|
||||
|
||||
* progmodes/cc-cmds.el (c-indent-line-or-region): Fix so that
|
||||
indenting a macro followed by blank lines doesn't backslash the
|
||||
following non-blank line into the macro.
|
||||
|
||||
@ -529,6 +529,10 @@ the previous one if already at the beginning of one. Only
|
||||
statements/declarations on the same level are considered, i.e. don't
|
||||
move into or out of sexps (not even normal expression parentheses).
|
||||
|
||||
If point is already at the earliest statment within braces or parens,
|
||||
this function doesn't move back into any whitespace preceding it; it
|
||||
returns 'same in this case.
|
||||
|
||||
Stop at statement continuation tokens like \"else\", \"catch\",
|
||||
\"finally\" and the \"while\" in \"do ... while\" if the start point
|
||||
is within the continuation. If starting at such a token, move to the
|
||||
@ -548,12 +552,16 @@ of the content in the macro, i.e. the expression of an \"#if\" or the
|
||||
start of the definition in a \"#define\". Also stop at start of
|
||||
macros before leaving them.
|
||||
|
||||
Return 'label if stopped at a label, 'same if stopped at the beginning
|
||||
of the current statement, 'up if stepped to a containing statement,
|
||||
'previous if stepped to a preceding statement, 'beginning if stepped
|
||||
from a statement continuation clause to its start clause, or 'macro if
|
||||
stepped to a macro start. Note that 'same and not 'label is returned
|
||||
if stopped at the same label without crossing the colon character.
|
||||
Return:
|
||||
'label if stopped at a label;
|
||||
'same if stopped at the beginning of the current statement;
|
||||
'up if stepped to a containing statement;
|
||||
'previous if stepped to a preceding statement;
|
||||
'beginning if stepped from a statement continuation clause to
|
||||
its start clause; or
|
||||
'macro if stepped to a macro start.
|
||||
Note that 'same and not 'label is returned if stopped at the same
|
||||
label without crossing the colon character.
|
||||
|
||||
LIM may be given to limit the search. If the search hits the limit,
|
||||
point will be left at the closest following token, or at the start
|
||||
@ -2509,7 +2517,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; Move to the beginning of the current token. Do not move if not
|
||||
;; in the middle of one. BACK-LIMIT may be used to bound the
|
||||
;; backward search; if given it's assumed to be at the boundary
|
||||
;; between two tokens. Return non-nil if the point is move, nil
|
||||
;; between two tokens. Return non-nil if the point is moved, nil
|
||||
;; otherwise.
|
||||
;;
|
||||
;; This function might do hidden buffer changes.
|
||||
@ -3319,7 +3327,7 @@ literal next to point is returned. \"Next to\" means there's only
|
||||
spaces and tabs between point and the literal. The search for such a
|
||||
literal is done first in forward direction. If NOT-IN-DELIMITER is
|
||||
non-nil, the case when point is inside a starting delimiter won't be
|
||||
recognized. This only has effect for comments, which have starting
|
||||
recognized. This only has effect for comments which have starting
|
||||
delimiters with more than one character.
|
||||
|
||||
Note that this function might do hidden buffer changes. See the
|
||||
@ -3429,9 +3437,10 @@ comment at the start of cc-engine.el for more info."
|
||||
|
||||
(defun c-literal-type (range)
|
||||
"Convenience function that given the result of `c-literal-limits',
|
||||
returns nil or the type of literal that the range surrounds. It's
|
||||
much faster than using `c-in-literal' and is intended to be used when
|
||||
you need both the type of a literal and its limits.
|
||||
returns nil or the type of literal that the range surrounds, one
|
||||
of the symbols 'c, 'c++ or 'string. It's much faster than using
|
||||
`c-in-literal' and is intended to be used when you need both the
|
||||
type of a literal and its limits.
|
||||
|
||||
Note that this function might do hidden buffer changes. See the
|
||||
comment at the start of cc-engine.el for more info."
|
||||
@ -3581,8 +3590,17 @@ comment at the start of cc-engine.el for more info."
|
||||
|
||||
(defun c-find-decl-spots (cfd-limit cfd-decl-re cfd-face-checklist cfd-fun)
|
||||
;; Call CFD-FUN for each possible spot for a declaration, cast or
|
||||
;; label from the point to CFD-LIMIT. Such a spot is:
|
||||
;; label from the point to CFD-LIMIT.
|
||||
;;
|
||||
;; CFD-FUN is called with point at the start of the spot. It's
|
||||
;; passed two arguments: The first is the end position of the token
|
||||
;; preceding the spot, or 0 for the implicit match at bob. The
|
||||
;; second is a flag that is t when the match is inside a macro. If
|
||||
;; CFD-FUN adds `c-decl-end' properties somewhere below the current
|
||||
;; spot, it should return non-nil to ensure that the next search
|
||||
;; will find them.
|
||||
;;
|
||||
;; Such a spot is:
|
||||
;; o The first token after bob.
|
||||
;; o The first token after the end of submatch 1 in
|
||||
;; `c-decl-prefix-or-start-re' when that submatch matches.
|
||||
@ -3602,14 +3620,6 @@ comment at the start of cc-engine.el for more info."
|
||||
;; outside it. It's to avoid this work that the CFD-DECL-RE and
|
||||
;; CFD-FACE-CHECKLIST checks exist.
|
||||
;;
|
||||
;; CFD-FUN is called with point at the start of the spot. It's
|
||||
;; passed two arguments: The first is the end position of the token
|
||||
;; preceding the spot, or 0 for the implicit match at bob. The
|
||||
;; second is a flag that is t when the match is inside a macro. If
|
||||
;; CFD-FUN adds `c-decl-end' properties somewhere below the current
|
||||
;; spot, it should return non-nil to ensure that the next search
|
||||
;; will find them.
|
||||
;;
|
||||
;; The spots are visited approximately in order from top to bottom.
|
||||
;; It's however the positions where `c-decl-prefix-or-start-re'
|
||||
;; matches and where `c-decl-end' properties are found that are in
|
||||
@ -5139,7 +5149,8 @@ comment at the start of cc-engine.el for more info."
|
||||
;; inside a function declaration arglist).
|
||||
;; '<> In an angle bracket arglist.
|
||||
;; 'arglist Some other type of arglist.
|
||||
;; nil Some other context or unknown context.
|
||||
;; nil Some other context or unknown context. Includes
|
||||
;; within the parens of an if, for, ... construct.
|
||||
;;
|
||||
;; LAST-CAST-END is the first token after the closing paren of a
|
||||
;; preceding cast, or nil if none is known. If
|
||||
@ -5487,6 +5498,7 @@ comment at the start of cc-engine.el for more info."
|
||||
at-decl-or-cast
|
||||
(catch 'at-decl-or-cast
|
||||
|
||||
;; CASE 1
|
||||
(when (> paren-depth 0)
|
||||
;; Encountered something inside parens that isn't matched by
|
||||
;; the `c-type-decl-*' regexps, so it's not a type decl
|
||||
@ -5510,6 +5522,7 @@ comment at the start of cc-engine.el for more info."
|
||||
(if got-identifier
|
||||
(progn
|
||||
|
||||
;; CASE 2
|
||||
(when (and (or at-type maybe-typeless)
|
||||
(not (or got-prefix got-parens)))
|
||||
;; Got another identifier directly after the type, so it's a
|
||||
@ -5536,6 +5549,7 @@ comment at the start of cc-engine.el for more info."
|
||||
(if backup-at-type
|
||||
(progn
|
||||
|
||||
;; CASE 3
|
||||
(when (= (point) start)
|
||||
;; Got a plain list of identifiers. If a colon follows it's
|
||||
;; a valid label. Otherwise the last one probably is the
|
||||
@ -5548,6 +5562,7 @@ comment at the start of cc-engine.el for more info."
|
||||
(setq backup-if-not-cast t)
|
||||
(throw 'at-decl-or-cast t)))
|
||||
|
||||
;; CASE 4
|
||||
(when (and got-suffix
|
||||
(not got-prefix)
|
||||
(not got-parens))
|
||||
@ -5558,6 +5573,7 @@ comment at the start of cc-engine.el for more info."
|
||||
(setq backup-if-not-cast t)
|
||||
(throw 'at-decl-or-cast t)))
|
||||
|
||||
;; CASE 5
|
||||
(when (eq at-type t)
|
||||
;; If the type is known we know that there can't be any
|
||||
;; identifier somewhere else, and it's only in declarations in
|
||||
@ -5567,6 +5583,7 @@ comment at the start of cc-engine.el for more info."
|
||||
|
||||
(when (= (point) start)
|
||||
;; Only got a single identifier (parsed as a type so far).
|
||||
;; CASE 6
|
||||
(if (and
|
||||
;; Check that the identifier isn't at the start of an
|
||||
;; expression.
|
||||
@ -5587,6 +5604,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; constants in C++.
|
||||
(memq at-type '(known found)))))
|
||||
(throw 'at-decl-or-cast t)
|
||||
;; CASE 7
|
||||
;; Can't be a valid declaration or cast, but if we've found a
|
||||
;; specifier it can't be anything else either, so treat it as
|
||||
;; an invalid/unfinished declaration or cast.
|
||||
@ -5620,7 +5638,7 @@ comment at the start of cc-engine.el for more info."
|
||||
(c-fdoc-shift-type-backward)
|
||||
|
||||
;; Still no identifier.
|
||||
|
||||
;; CASE 8
|
||||
(when (and got-prefix (or got-parens got-suffix))
|
||||
;; Require `got-prefix' together with either `got-parens' or
|
||||
;; `got-suffix' to recognize it as an abstract declarator:
|
||||
@ -5633,6 +5651,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; the point when the fontification was invoked.
|
||||
(throw 'at-decl-or-cast t))
|
||||
|
||||
;; CASE 9
|
||||
(when (and at-type
|
||||
(not got-prefix)
|
||||
(not got-parens)
|
||||
@ -5643,11 +5662,13 @@ comment at the start of cc-engine.el for more info."
|
||||
;; instantiation expression).
|
||||
(throw 'at-decl-or-cast nil))))
|
||||
|
||||
;; CASE 10
|
||||
(when at-decl-or-cast
|
||||
;; By now we've located the type in the declaration that we know
|
||||
;; we're in.
|
||||
(throw 'at-decl-or-cast t))
|
||||
|
||||
;; CASE 11
|
||||
(when (and got-identifier
|
||||
(not context)
|
||||
(looking-at c-after-suffixed-type-decl-key)
|
||||
@ -5666,6 +5687,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; A declaration according to `c-after-suffixed-type-decl-key'.
|
||||
(throw 'at-decl-or-cast t))
|
||||
|
||||
;; CASE 12
|
||||
(when (and (or got-prefix (not got-parens))
|
||||
(memq at-type '(t known)))
|
||||
;; It's a declaration if a known type precedes it and it can't be a
|
||||
@ -5696,11 +5718,13 @@ comment at the start of cc-engine.el for more info."
|
||||
;; Below are tests that only should be applied when we're certain to
|
||||
;; not have parsed halfway through an expression.
|
||||
|
||||
;; CASE 14
|
||||
(when (memq at-type '(t known))
|
||||
;; The expression starts with a known type so treat it as a
|
||||
;; declaration.
|
||||
(throw 'at-decl-or-cast t))
|
||||
|
||||
;; CASE 15
|
||||
(when (and (c-major-mode-is 'c++-mode)
|
||||
;; In C++ we check if the identifier is a known type, since
|
||||
;; (con|de)structors use the class name as identifier.
|
||||
@ -5734,6 +5758,7 @@ comment at the start of cc-engine.el for more info."
|
||||
|
||||
(if got-identifier
|
||||
(progn
|
||||
;; CASE 16
|
||||
(when (and got-prefix-before-parens
|
||||
at-type
|
||||
(or at-decl-end (looking-at "=[^=]"))
|
||||
@ -5746,6 +5771,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; be a function call.
|
||||
(throw 'at-decl-or-cast t))
|
||||
|
||||
;; CASE 17
|
||||
(when (and (or got-suffix-after-parens
|
||||
(looking-at "=[^=]"))
|
||||
(eq at-type 'found)
|
||||
@ -5756,6 +5782,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; somewhere else (if it's a known type we won't get here).
|
||||
(throw 'at-decl-or-cast t)))
|
||||
|
||||
;; CASE 18
|
||||
(when (and context
|
||||
(or got-prefix
|
||||
(and (eq context 'decl)
|
||||
@ -6245,10 +6272,14 @@ comment at the start of cc-engine.el for more info."
|
||||
(looking-at c-opt-asm-stmt-key))))
|
||||
|
||||
(defun c-at-toplevel-p ()
|
||||
"Return a determination as to whether point is at the `top-level'.
|
||||
Being at the top-level means that point is either outside any
|
||||
enclosing block (such function definition), or only inside a class,
|
||||
namespace or other block that contains another declaration level.
|
||||
"Return a determination as to whether point is \"at the top level\".
|
||||
Informally, \"at the top level\" is anywhere where you can write
|
||||
a function.
|
||||
|
||||
More precisely, being at the top-level means that point is either
|
||||
outside any enclosing block (such as a function definition), or
|
||||
directly inside a class, namespace or other block that contains
|
||||
another declaration level.
|
||||
|
||||
If point is not at the top-level (e.g. it is inside a method
|
||||
definition), then nil is returned. Otherwise, if point is at a
|
||||
@ -8178,7 +8209,7 @@ comment at the start of cc-engine.el for more info."
|
||||
;; member init list continuation, or a template argument
|
||||
;; list continuation.
|
||||
((save-excursion
|
||||
;; Note: We use the fact that lim always is after any
|
||||
;; Note: We use the fact that lim is always after any
|
||||
;; preceding brace sexp.
|
||||
(if c-recognize-<>-arglists
|
||||
(while (and
|
||||
|
||||
Loading…
Reference in New Issue
Block a user