emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] emacs/doc/misc ChangeLog sem-user.texi semantic...


From: Chong Yidong
Subject: [Emacs-diffs] emacs/doc/misc ChangeLog sem-user.texi semantic...
Date: Sat, 28 Nov 2009 21:09:01 +0000

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/11/28 21:09:00

Modified files:
        doc/misc       : ChangeLog sem-user.texi semantic.texi 

Log message:
        * semantic.texi (Analyzer Internals): Rename from Analyzer.
        
        * sem-user.texi (Semantic mode user commands): Fix key syntax.
        Document semantic-complete-analyze-inline.
        (Semanticdb search debugging commands): Minor clarification.
        (Analyzer, Smart Completion, Smart Summary, Smart Jump)
        (Analyzer Debug) New nodes, adapted from the upstream Semantic user
        manual.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/ChangeLog?cvsroot=emacs&r1=1.350&r2=1.351
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/sem-user.texi?cvsroot=emacs&r1=1.5&r2=1.6
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/semantic.texi?cvsroot=emacs&r1=1.2&r2=1.3

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/ChangeLog,v
retrieving revision 1.350
retrieving revision 1.351
diff -u -b -r1.350 -r1.351
--- ChangeLog   28 Nov 2009 20:36:05 -0000      1.350
+++ ChangeLog   28 Nov 2009 21:09:00 -0000      1.351
@@ -1,3 +1,14 @@
+2009-11-28  Chong Yidong  <address@hidden>
+
+       * semantic.texi (Analyzer Internals): Rename from Analyzer.
+
+       * sem-user.texi (Semantic mode user commands): Fix key syntax.
+       Document semantic-complete-analyze-inline.
+       (Semanticdb search debugging commands): Minor clarification.
+       (Analyzer, Smart Completion, Smart Summary, Smart Jump)
+       (Analyzer Debug) New nodes, adapted from the upstream Semantic user
+       manual.
+
 2009-11-28  Kevin Ryde  <address@hidden>
 
        * cl.texi (Porting Common Lisp): Update EIEIO dead ftp link to a

Index: sem-user.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/sem-user.texi,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- sem-user.texi       20 Nov 2009 05:02:46 -0000      1.5
+++ sem-user.texi       28 Nov 2009 21:09:00 -0000      1.6
@@ -28,6 +28,7 @@
 * Semantic mode::   Global minor mode for @semantic{}.
 * SemanticDB::      Caching parsed buffers between sessions.
 * Idle Scheduler::  Performing @semantic{} operations when idle.
+* Analyzer::        Semantic tools for analyzing code.
 @end menu
 
 @node Semantic mode
@@ -107,64 +108,70 @@
 point.
 
 @table @kbd
address@hidden \C-c , j
address@hidden C-c , j
 Prompt for a tag defined in the current file, and move point to it
 (@code{semantic-complete-jump-local}).
 
address@hidden \C-c , J
address@hidden C-c , J
 Prompt for a tag defined in any file that Emacs has parsed, and move
 point to it (@code{semantic-complete-jump}).
 
address@hidden \C-c , l
address@hidden C-c , l
 Display a list of the possible completions of the current tag
 (@code{semantic-analyze-possible-completions}).
 
address@hidden \C-c , g
address@hidden C-c , g
 Prompt for a tag, and display a list of tags that call it
 (@code{semantic-symref-symbol}).
 
address@hidden \C-c , G
address@hidden C-c , G
 Display a list of tags that call the current tag
 (@code{semantic-symref}).
 
address@hidden \C-c , p
address@hidden C-c , p
 Move point to the previous tag (@code{senator-previous-tag}).
 
address@hidden \C-c , n
address@hidden C-c , n
 Move point to the next tag (@code{senator-next-tag}).
 
address@hidden \C-c , u
address@hidden C-c , u
 Move point ``up'' one reference (@code{senator-go-to-up-reference}).
 The meaning of ``up'' is language-dependent; in C++, for instance,
 this means moving to the parent of the current tag.
 
address@hidden \C-c, @key{SPC}
-(@code{semantic-complete-analyze-inline})
address@hidden C-c, @key{SPC}
+Display a list of possible completions for the symbol at point
+(@code{semantic-complete-analyze-inline}).  This also activates a
+special set of keybindings for choosing a completion: @key{RET}
+accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
+possible completions, @key{TAB} completes as far as possible and then
+cycles, and @kbd{C-g} or any other key aborts the completion.
address@hidden Completion}.
 
address@hidden \C-c,\C-w
address@hidden C-c , C-w
 Kill the current tag (@code{senator-kill-tag}).  This removes the text
 for that tag, placing it in the kill ring.  You can retrieve the text
 with @kbd{C-y}.  This also places the tag in the @dfn{tag ring}, so
 that you can yank it with @kbd{\C-c,\C-y}, below.
 
address@hidden \C-c,\M-w
address@hidden C-c , M-w
 Copy the current tag into the kill ring as well as the tag ring
 (@code{senator-copy-tag}).
 
address@hidden \C-c,\C-y
address@hidden C-c , C-y
 Yank a tag from the tag ring (@code{senator-yank-tag}).
 
address@hidden \C-c,r
address@hidden C-c , r
 Copy the current tag into a register
 (@code{senator-copy-tag-to-register}).  With an optional argument,
 kill it as well.  This allows you to insert or jump to that tag with
 the usual register commands.  @xref{Registers,,,emacs,Emacs manual}.
 
address@hidden ?\C-c , @kbd{up}
address@hidden \C-c , @kbd{up}
 Transpose the current tag with the previous one
 (@code{senator-transpose-tags-up}).
 
address@hidden ?\C-c ?, @kbd{down}
address@hidden C-c , @kbd{down}
 Transpose the current tag with the next one
 (@code{senator-transpose-tags-down}).
 @end table
@@ -433,7 +440,6 @@
 list of databases that will be searched from a given buffer.  You can
 follow up with @kbd{M-x semanticdb-find-test-translate-path} to then
 make sure specific tables from the path are discovered correctly.
-
 Alternately, you can get a list of include files @semantic{}
 encountered, but could not find on disk using @kbd{M-x
 semanticdb-find-adebug-lost-includes}.
@@ -443,10 +449,11 @@
 Dump a list of all databases in Emacs memory.
 @end deffn
 
address@hidden Command semanticdb-find-test-translate-path &optional arg
 @anchor{semanticdb-find-test-translate-path}
-Call and output results of @dfn{semanticdb-find-translate-path}
-With @var{arg} address@hidden, specify a @var{brutish} translation.
address@hidden Command semanticdb-find-test-translate-path &optional arg
+Call and output results of @dfn{semanticdb-find-translate-path}.  In
+the displayed buffer, you can type @key{SPC} to expand items.  With
address@hidden address@hidden, specify a @var{brutish} translation.
 @end deffn
 
 @deffn Command semanticdb-find-adebug-lost-includes
@@ -681,8 +688,8 @@
 displayed inline, with keybindings that allow you to cycle through
 different alternatives.
 
address@hidden   @xref{Analyzer}, for information about code
address@hidden completion.
+Semantic Idle Completions mode performs completion based on the
+Semantic Analyzer (@pxref{Analyzer}).
 
 @anchor{global-semantic-idle-completions-mode}
 @anchor{semantic-idle-completions-mode}
@@ -761,3 +768,337 @@
 Display completions in a separate window.
 @end table
 @end deffn
+
address@hidden Analyzer
address@hidden Analyzer
address@hidden Analyzer
+
+The Semantic Analyzer is a library for performing context analysis on
+source code.  It provides user commands for displaying, completing,
+and navigating through source code.
+
address@hidden
+* Smart Completion::       Performing code completion.
+* Smart Summary::          Displaying help on a symbol.
+* Smart Jump::             Jumping to the definition of a tag.
+* Analyzer Debug::         Debugging problems with the analyzer.
address@hidden menu
+
address@hidden Smart Completion
address@hidden Smart Completion
+
+The Semantic Analyzer can be used to perform code completion in a
+manner that takes the local context into account.
+
+In addition to the user commands documented in this section, the
+completions performed by Semantic Idle Completions mode also uses the
+Semantic Analyzer.  @xref{Idle Completions Mode}.
+
address@hidden Command semantic-analyze-possible-completions context
+This is the most basic command for Semantic Analyzer-based completion.
+Called interactively, it displays in another window a list of the
+possible completions for the symbol at point.
+
+When called from a Lisp program,
address@hidden does not display a
+completions list.  The argument @var{context} should be either a
+buffer position, or a context object.  The return value is a list of
address@hidden tag objects that complete the symbol for @var{context},
+based on the following criteria:
+
address@hidden
address@hidden Elements currently in scope.
address@hidden Constants currently in scope.
address@hidden Elements matching the context's @code{:prefix}.
address@hidden Type of the completion matching the type of the context.
address@hidden itemize
+
+Most of the other commands documented in this section call
address@hidden internally.
address@hidden deffn
+
address@hidden
address@hidden Command semantic-complete-analyze-inline
+This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is
+enabled (@pxref{Semantic mode user commands}).  It displays a list of
+possible completions for the symbol at point, and activates a special
+set of keybindings for choosing a completion.
+
+You can type @key{RET} to accept the current completion, @kbd{M-n} and
address@hidden to cycle through the possible completions, @key{TAB} to
+complete as far as possible and then cycle through completions, and
+either @kbd{C-g} or any other key to abort the completion.
+
+This command is similar to the completion performed by Semantic Idle
+Completions mode.  The main difference is that it is called
+explicitly, whereas Semantic Idle Completions mode completes during
+idle time (@pxref{Idle Completions Mode}).
address@hidden deffn
+
address@hidden
address@hidden Option semantic-complete-inline-analyzer-idle-displayor-class
+The value of this variable determines how
address@hidden shows its completions.
+Possible values include:
+
address@hidden @code
address@hidden semantic-displayor-traditional
+Display completions in a separate window.  This is the default value.
+
address@hidden semantic-displayor-ghost
+Display completions ``inline'' with the buffer text, similar to the
+default behavior of Semantic Idle Completions mode (@pxref{Idle
+Completions Mode}).
+
address@hidden semantic-displayor-tooltip
+Display completions in a tooltip.
address@hidden table
address@hidden deffn
+
+In addition to @code{semantic-complete-analyze-inline}, you can use
+the simpler command @code{semantic-ia-complete-symbol point}.  This
+behaves like the usual @address@hidden (@code{complete-symbol})
+command (@pxref{Symbol Completion,,,emacs,Emacs manual}), except it
+uses Semantic Analyzer.
+
address@hidden
address@hidden Command semantic-ia-complete-symbol point
+Complete the current symbol at @var{point}.
address@hidden deffn
+
address@hidden Smart Summary
address@hidden Smart Summary
+
+You can use the commands in this section to find information about the
+code at point:
+
address@hidden
address@hidden Command semantic-ia-show-summary pos
+Display a summary for the symbol at @var{pos}.  Called interactively,
address@hidden defaults to point.
address@hidden deffn
+
address@hidden
address@hidden Command semantic-ia-show-doc pos
+Display the code-level documentation for the symbol at @var{pos}.
+Called interactively, @var{pos} defaults to point.
address@hidden deffn
+
address@hidden
address@hidden Command semantic-ia-describe-class typename
+Prompt for the name of a data type, @var{typename}, and display its
+components.  For instance, if the type in question is a class, this
+displays the methods and member variables.
address@hidden deffn
+
+You can also use Semantic Idle Summary mode to show information about
+the current symbol in the echo area during idle time.  @xref{Idle
+Summary Mode}.
+
address@hidden Smart Jump
address@hidden Smart Jump
+
+The Semantic Analyzer can be used to jump directly to the definition
+for a code symbol.  Because it is based on code analysis, its behavior
+is often more accurate than than the @code{find-tag} command
+(@pxref{Tags,,,emacs,Emacs manual}).
+
address@hidden
address@hidden Command semantic-ia-fast-jump pos
+Jump to the definition for the symbol at @var{pos}.  Called
+interactively, @var{pos} defaults to point.
address@hidden deffn
+
address@hidden
address@hidden semantic-ia-fast-mouse-jump event
+Jump to the definition for the symbol at the position of the mouse
+event @var{event}.  This command is meant to be bound to a mouse
+command, like this:
+
address@hidden
+(global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump)
address@hidden example
address@hidden defun
+
+You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local})
+and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags.
address@hidden mode user commands}.  Those commands do not make use of
+the Semantic Analyzer.
+
address@hidden Analyzer Debug
address@hidden Debugging the Semantic Analyzer
+
+In the event that the Semantic Analyzer does not analyze your code
+properly, you can take steps to identify and solve the problem.  This
+section was written with C/C++ in mind, but should be relevant for any
+typed language.
+
address@hidden Step 1: Check the context
+
+The first thing to do is check the current context.  You can do this
+with @kbd{M-x semantic-analyze-current-context}.
+
address@hidden Command semantic-analyze-current-context pos
+Analyze the context at @var{pos}.  This function is used by most of
+the other Semantic Analyzer commands to obtain the context of the code
+at a given buffer position.  The return value is an EIEIO object
+describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO
+manual}).
+
+When called interactively, this displays a @samp{*Semantic Context
+Analysis*} buffer in a separate window.  This buffer contains a
+summary of the context at point.
address@hidden deffn
+
+The Prefix section of the @samp{*Semantic Context Analysis*} buffer
+lists the tags based on the text at point.  If it shows only a simple
+string, the Semantic was unable to identify what the data type was.
+
+The first item in the list of the prefix is the first lookup failure
+in the chain, and that is the item to focus debugging effort on.  For
+example:
+
address@hidden
+Context Type: #<semantic-analyze-context context>
+Bounds: (182 . 185)
+Prefix: Foo* bar
+        int bbb (const char* y)
+Prefix Types: class Foo @address@hidden
+--------
+-> Local Vars: int argc
+               char** argv
address@hidden example
+
+In this example you can see that the prefix has two fully found tags.
+In the following example, the symbol ``bbb'' is incomplete, and could
+not be found:
+
address@hidden
+Context Type: #<semantic-analyze-context context>
+Bounds: (182 . 184)
+Prefix: Foo* bar
+        "bb"
+Prefix Classes: 'function
+                'variable
+Prefix Types: class Foo @address@hidden
+--------
+-> Local Vars: int argc
+               char** argv
address@hidden example
+
address@hidden Step 2 : Check your include path
+
+Once you know what symbol can't be found, the next thing to check is
+your include path.  Is the header or include file that has the
+definitions you need actually in the list of headers @semantic{} is
+searching through?  To get a basic list, you can use @kbd{M-x
+semanticdb-find-test-translate-path}.  @xref{Semanticdb search
+debugging commands}.
+
+For C++, check to make sure that your project level include files are
+in quotes, and not angle brackets.  Items in angle brackets are system
+includes.
+
+If items should be loaded but aren't, you may need to update the
+search throttle.  @xref{Search Throttle}.  If you see some tables that
+have 0 tags in them, then you you may have an incorrectly set
+throttle.  For example,
+
address@hidden
+*#<semanticdb-table main.cpp (4 tags DIRTY)>
+*#<semanticdb-table foo.hh (0 tags DIRTY)>
address@hidden example
+
+Here, @semantic{} found @file{foo.hh}, but there are 0 tags.  This may
+be because the throttle was set to not read in and parse files that
+Emacs has not yet loaded in.  To fix this case, visit the file, and
+let @semantic{} parse and save the tags table.
+
address@hidden Step 3: Check the local scope
+
+If your data type is somehow abbreviated based on scope, such as from
+a @code{using} statement, you should make sure that the symbol you
+want is in the local scope.  Examine the scope with @kbd{M-x
+semantic-calculate-scope}.  The scope structure is displayed in ADEBUG
+mode, so use @kbd{SPC} to expand different elements and looking for
+your symbol.
+
+If your symbol should be in the scope, but you cannot find it, then
+you may have found a language support bug in the local-variable
+parser, or using statement parser.
+
+Calling @kbd{M-x bovinte} should force a reset on the scope in case
+there is merely some bad state.
+
address@hidden
+ ] Name: Cache
+ ] Class: #'semantic-scope-cache
+ ] :table #<semanticdb-table testsubclass.cpp (13 tags DIRTY)>
+ ] tag createMoose : class moose
+ ] scopetypes 'nil
+ ] parents #<TAG LIST: 1 entries>
+ ] scope #<TAG LIST: 22 entries>
+ ] fullscope #<TAG LIST: 23 entries>
+ ] localvar #<TAG LIST: 6 entries>
address@hidden example
+
+In the above sample output, the @code{tag} slot specifies where within
+you source this scope is relevant.  @code{Parents} should contain any
+in scope parents, such as the class a method belongs to.
address@hidden should contain your local variables.  @code{Scope}
+should contain datatypes in scope due to a @code{using} statement or
+the like.
+
address@hidden Step 4: Check the typecache
+
+For complex typed languages like C++, @semantic{} creates a typecache,
+or an optimized search table with all the various data types in it.
+Elements in the typecache do not obey local scope.  It only contains
+fully qualified names.  You can examine the typecache with
address@hidden semanticdb-typecache-dump}.
+
+If your data types are not in the typecache, there may be some parsing
+error or other bug.  Calling @kbd{M-x bovinte} should force a reset on
+the typecache in case there is merely some bad state.
+
address@hidden
+]#<semanticdb-typecache /home/zappo/cedet/semantic/tests/testsubclass.cpp>
+   ] Name: /home/zappo/cedet/semantic/tests/testsubclass.cpp
+   ] Class: #'semanticdb-typecache
+   ] filestream 'nil
+   ] includestream #<TAG LIST: 84 entries>
+   ] stream 'nil
+   ] dependants 'nil
address@hidden example
+
+In the above example, the output of @kbd{M-x semanticdb-typecache-dump}
+was expanded one level.  The @code{filestream} slot should contain
+datatypes in the current file.  The @code{includestream} should
+contain all the datatypes in all included header files.
+
+The @code{dependants} slot will specify other files that depend on
+this one.
+
address@hidden Step 5: Check the parser
+
+Go to the location where your unfound tag should be.  You can call
address@hidden bovinate}, and see a dump of the raw tag structure.  To see a
+navigable tree, use @kbd{M-x semantic-adebug-bovinate} instead.  You
+can then look to make sure your tag has been properly parsed.
+
+If it has not, then you may have found a parser bug.  To get a feel
+how @semantic{} treats your file, type @kbd{M-x
+global-semantic-show-unmatched-syntax-mode}.  This causes any syntax
+it cannot parse to be underlined in red.
+
+If your type is not parsable, it could be for a couple of reasons:
+
address@hidden
address@hidden
+If there is a MACRO keyword used in the definition of the type, you
+may need to update the @code{semantic-lex-c-preprocessor-symbol-map}
+to account for it.
+
address@hidden
+Or perhaps the parser needs to be fixed.
address@hidden enumerate

Index: semantic.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/semantic.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- semantic.texi       17 Nov 2009 01:52:48 -0000      1.2
+++ semantic.texi       28 Nov 2009 21:09:00 -0000      1.3
@@ -240,8 +240,8 @@
 @menu
 * Parser code ::         Code used for the parsers
 * Tag handling ::        Code used for manipulating tags
-* Semanticdb internals :: Code used in the semantic database
-* Analyzer ::             Code used in the code analyzer
+* Semanticdb Internals :: Code used in the semantic database
+* Analyzer Internals ::   Code used in the code analyzer
 * Tools ::                Code used in user tools
 * Tests ::                Code used for testing
 @end menu
@@ -349,8 +349,8 @@
 
 @end table
 
address@hidden Semanticdb internals
address@hidden Semanticdb internals
address@hidden Semanticdb Internals
address@hidden Semanticdb Internals
 
 @acronym{Semanticdb} complexity is certainly an issue.  It is a rather
 hairy problem to try and solve.
@@ -400,8 +400,8 @@
 
 @end table
 
address@hidden Analyzer
address@hidden Analyzer
address@hidden Analyzer Internals
address@hidden Analyzer Internals
 
 The @semantic{} analyzer is a complex engine which has been broken
 down across several modules.  When the @semantic{} analyzer fails,




reply via email to

[Prev in Thread] Current Thread [Next in Thread]