tagbar/doc/tagbar.txt

*tagbar.txt*	Display tags of a file in their correct scope

Author:		Jan Larres <jan@majutsushi.net>
Licence:	Vim licence, see |license|

==============================================================================
Contents					*tagbar* *tagbar-contents*

	 1. Intro ........................... |tagbar-intro|
	    Pseudo-tags ..................... |tagbar-pseudotags|
	    Supported features .............. |tagbar-features|
	 2. Requirements .................... |tagbar-requirements|
	 3. Installation .................... |tagbar-installation|
	 4. Usage ........................... |tagbar-usage|
	 5. Commands ........................ |tagbar-commands|
	 6. Configuration ................... |tagbar-configuration|
	 7. Adding your own file types ...... |tagbar-add-types|
	 8. Bugs and limitations ............ |tagbar-bugs|
	 9. History ......................... |tagbar-history|
	10. Todo ............................ |tagbar-todo|

==============================================================================
1. Intro							*tagbar-intro*

Tagbar is a plugin for browsing the tags of source code files. It provides a
sidebar that displays the ctags-generated tags of the current file, ordered by
their correct scope. This means that for example methods in C++ are displayed
under the class they are defined in.

Let's say we have the following code inside of a C++ file:
>
    namespace {
        char a;

        class Foo
        {
        public:
            Foo();
            ~Foo();
        private:
            int var;
        };
    };
<
Then Tagbar would display the tag information like so:
>
    __anon1* : namespace
      Foo : class
       +Foo()
       +~Foo()
       -var
      a
<
This example shows several important points. First, the tags are listed
indented below the scope they are defined in. Second, the type of a scope is
listed after its name and a colon. Third, tags for which the access/visibility
information is known are prefixed with a symbol indicating that.


PSEUDO-TAGS						*tagbar-pseudotags*

The example also introduces the concept of "pseudo-tags". Pseudo-tags are tags
that are not explicitly defined in the file but have children in it. In this
example the namespace doesn't have a name and thus ctags doesn't generate a
tag for it, but since it has children it still needs to be displayed using an
auto-generated name.

Another case where pseudo-tags appear is in C++ implementation files. Since
classes are usually defined in a header file but the member methods and
variables in the implementation file the class itself won't generate a tag
in that file.

Pseudo-tags are denoted with an asterisk ('*') at the end of their name.


SUPPORTED FEATURES					*tagbar-features*

The following features are supported by Tagbar:

    - Display tags under their correct scope.
    - Automatically update the tags when switching between buffers and
      editing files.
    - Display visibility information of tags if available.
    - Highlight the tag near the cursor while editing files.
    - Jump to a tag from the Tagbar window.
    - Display the complete prototype of a tag.
    - Tags can be sorted either by name or order of appearance in the file.
    - Scopes can be folded to hide uninteresting information.
    - Supports all of the languages that ctags does, i.e. Ant, Assembler, ASP,
      Awk, Basic, BETA, C, C++, C#, COBOL, DosBatch, Eiffel, Erlang, Flex,
      Fortran, HTML, Java, JavaScript, Lisp, Lua, Make, MatLab, OCaml, Pascal,
      Perl, PHP, Python, REXX, Ruby, Scheme, Shell script, SLang, SML, SQL,
      Tcl, Tex, Vera, Verilog, VHDL, Vim and YACC.
    - Can be extended to support arbitrary new types.

==============================================================================
2. Requirements						*tagbar-requirements*

The following requirements have to be met in order to be able to use tagbar:

    - Vim 7.0 or higher. Older versions will not work since Tagbar uses data
      structures that were only introduced in Vim 7.
    - Exuberant ctags 5.0 or higher. Ctags is the program that generates the
      tag information that Tagbar uses. It is shipped with most Linux
      distributions, otherwise it can be downloaded from the following
      website:

          http://ctags.sourceforge.net/

      Tagbar will work on any platform that ctags runs on -- this includes
      UNIX derivatives, Mac OS X and Windows. Note that other versions like
      GNU ctags will not work.
      Tagbar generates the tag information by itself and doesn't need already
      existing tag files.
    - File type detection must be turned on in vim. This can be done with the
      following command in your vimrc:
>
          filetype on
<
      See |filetype| for more information.
    - Tagbar will not work in |restricted-mode|.


caveats:
C++:
foo::Bar::init()
foo::Baz::method()
type of 'foo' is unknown (sorting problems), foo::Bar and foo::Baz listed
separately

class test:
    class Inner:
        def __init__(self):
            print "Inner"

def test():
    class Inner2:
        def __init__(self):
            print "Inner2"