Any suggestions are highly welcome. I'd prefer something that can be used in insert mode, as I think that makes it much more usable.
On Wed, Jan 9, 2013 at 10:55 PM, Nico Weber <[email protected]> wrote: > On Wed, Jan 9, 2013 at 1:49 PM, Daniel Jasper <[email protected]> wrote: > > Author: djasper > > Date: Wed Jan 9 15:49:28 2013 > > New Revision: 172004 > > > > URL: http://llvm.org/viewvc/llvm-project?rev=172004&view=rev > > Log: > > Add documentation for clang-format. > > > > This adds documentation for both LibFormat as well as the standalone > > tools and integrations built on top of it. It slightly restructures > > the ClangTools documentation. > > > > Added: > > cfe/trunk/docs/ClangCheck.rst > > cfe/trunk/docs/ClangFormat.rst > > cfe/trunk/docs/LibFormat.rst > > Modified: > > cfe/trunk/docs/ClangTools.rst > > cfe/trunk/docs/index.rst > > > > Added: cfe/trunk/docs/ClangCheck.rst > > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangCheck.rst?rev=172004&view=auto > > > ============================================================================== > > --- cfe/trunk/docs/ClangCheck.rst (added) > > +++ cfe/trunk/docs/ClangCheck.rst Wed Jan 9 15:49:28 2013 > > @@ -0,0 +1,36 @@ > > +========== > > +ClangCheck > > +========== > > + > > +`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be > used to > > +do basic error checking and AST dumping. > > + > > +.. code-block:: console > > + > > + $ cat <<EOF > snippet.cc > > + > void f() { > > + > int a = 0 > > + > } > > + > EOF > > + $ ~/clang/build/bin/clang-check snippet.cc -ast-dump -- > > + Processing: > /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc. > > + /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: > error: expected ';' at end of > > + declaration > > + int a = 0 > > + ^ > > + ; > > + (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>> > > + (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128') > > + (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned > __int128') > > + (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list > '__va_list_tag [1]') > > + (FunctionDecl 0x7ff3a302a8d0 > </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> > f 'void (void)' > > + (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1> > > + (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1> > > + (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int' > > + (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0)))))) > > + 1 error generated. > > + Error while processing snippet.cc. > > + > > +The '--' at the end is important as it prevents `clang-check` from > search for a > > +compilation database. For more information on how to setup and use > `clang-check` > > +in a project, see :doc:`HowToSetupToolingForLLVM`. > > > > Added: cfe/trunk/docs/ClangFormat.rst > > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangFormat.rst?rev=172004&view=auto > > > ============================================================================== > > --- cfe/trunk/docs/ClangFormat.rst (added) > > +++ cfe/trunk/docs/ClangFormat.rst Wed Jan 9 15:49:28 2013 > > @@ -0,0 +1,94 @@ > > +=========== > > +ClangFormat > > +=========== > > + > > +`ClangFormat` describes a set of tools that are built on top of > > +:doc:`LibFormat`. It can support your workflow in a variety of ways > including a > > +standalone tool and editor integrations. > > + > > + > > +Standalone Tool > > +=============== > > + > > +`clang-format` is part of the `clang/tools/extra` (see > > +:doc:`ClangTools <ClangTools>`) repository and can be used to format > > +C/C++/Obj-C code. > > + > > +.. code-block:: console > > + > > + $ clang-format --help > > + OVERVIEW: A tool to format C/C++/Obj-C code. > > + > > + Currently supports LLVM and Google style guides. > > + If no arguments are specified, it formats the code from standard input > > + and writes the result to the standard output. > > + If <file> is given, it reformats the file. If -i is specified together > > + with <file>, the file is edited in-place. Otherwise, the result is > > + written to the standard output. > > + > > + USAGE: clang-format [options] [<file>] > > + > > + OPTIONS: > > + -fatal-assembler-warnings - Consider warnings as error > > + -help - Display available options (-help-hidden > for more) > > + -i - Inplace edit <file>, if specified. > > + -length=<int> - Format a range of this length, -1 for > end of file. > > + -offset=<int> - Format a range starting at this file > offset. > > + -stats - Enable statistics output from program > > + -style=<string> - Coding style, currently supports: LLVM, > Google. > > + -version - Display the version of this program > > + > > + > > +Vim Integration > > +=============== > > + > > +There is an integration for `vim` which lets you run the `clang-format` > > +standalone tool on your current buffer, optionally selecting regions to > > +reformat. The integration has to form of a `python`-file which can be > found > > +under `clang/tools/extra/clang-format/clang-format.py`. > > + > > +This can be integrated by mapping the following to your `.vimrc`: > > + > > +.. code-block:: console > > + > > + map <C-I> :pyf <path-to-this-file>/clang-format.py<CR> > > + imap <C-I> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i > > Since this is now fairly official docs, can we come up with a shortcut > that doesn't override an relatively common existing shortcut? > > > + > > +The first line enables `clang-format` for NORMAL and VISUAL mode, the > second > > +line adds support for INSER` mode. Change "C-I" to another binding if > you > > +need clang-format on a different key (C-I stands for Ctrl+i). > > + > > +With this integration you can press the bound key and clang-format will > > +format the current line in NORMAL and INSERT mode or the selected > region in > > +VISUAL mode. The line or region is extended to the next bigger syntactic > > +entity. > > + > > +It operates on the current, potentially unsaved buffer and does not > create > > +or save any files. To revert a formatting, just undo. > > + > > + > > +Script for patch reformatting > > +============================= > > + > > +The python script `clang/tools/extra/clang-format-diff.py` parses the > output of > > +a unified diff and reformats all contained lines with `clang-format`. > > + > > +.. code-block:: console > > + > > + usage: clang-format-diff.py [-h] [-p P] [-style STYLE] > > + > > + Reformat changed lines in diff > > + > > + optional arguments: > > + -h, --help show this help message and exit > > + -p P strip the smallest prefix containing P slashes > > + -style STYLE formatting style to apply (LLVM, Google) > > + > > +So to reformat all the lines in the latest `git` commit, just do: > > + > > +.. code-block:: console > > + > > + git diff -U0 HEAD^ | clang-format-diff.py > > + > > +The `-U0` will create a diff without context lines (the script would > format > > +those as well). > > > > Modified: cfe/trunk/docs/ClangTools.rst > > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangTools.rst?rev=172004&r1=172003&r2=172004&view=diff > > > ============================================================================== > > --- cfe/trunk/docs/ClangTools.rst (original) > > +++ cfe/trunk/docs/ClangTools.rst Wed Jan 9 15:49:28 2013 > > @@ -1,9 +1,9 @@ > > -=========== > > -Clang Tools > > -=========== > > +======== > > +Overview > > +======== > > > > Clang Tools are standalone command line (and potentially GUI) tools > > -design for use by C++ developers who are already using and enjoying > > +designed for use by C++ developers who are already using and enjoying > > Clang as their compiler. These tools provide developer-oriented > > functionality such as fast syntax checking, automatic formatting, > > refactoring, etc. > > @@ -73,14 +73,25 @@ > > ``clang-check`` > > --------------- > > > > -This tool combines the LibTooling framework for running a Clang tool > > -with the basic Clang diagnostics by syntax checking specific files in a > > -fast, command line interface. It can also accept flags to re-display the > > -diagnostics in different formats with different flags, suitable for use > > -driving an IDE or editor. Furthermore, it can be used in fixit-mode to > > -directly apply fixit-hints offered by clang. > > - > > -FIXME: Link to user-oriented clang-check documentation. > > +:doc:`ClangCheck` combines the LibTooling framework for running a > > +Clang tool with the basic Clang diagnostics by syntax checking specific > files > > +in a fast, command line interface. It can also accept flags to > re-display the > > +diagnostics in different formats with different flags, suitable for use > driving > > +an IDE or editor. Furthermore, it can be used in fixit-mode to directly > apply > > +fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for > > +instructions on how to setup and used `clang-check`. > > + > > +``clang-format`` > > +~~~~~~~~~~~~~~~~ > > + > > +Clang-format is both a :doc:`library <LibFormat>` and a > :doc:`stand-alone tool > > +<ClangFormat>` with the goal of automatically reformatting C++ sources > files > > +according to configurable style guides. To do so, clang-format users > Clang's > > +Lexer to transform an input file into a token stream and then changes > all the > > +whitespace around those tokens. The goal is for clang-format to both > serve > > +both as a user tool (ideally with powerful IDE integrations) and part > of other > > +refactoring tools, e.g. to do a reformatting of all the lines changed > during a > > +renaming. > > > > Extra Clang Tools > > ================= > > > > Added: cfe/trunk/docs/LibFormat.rst > > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibFormat.rst?rev=172004&view=auto > > > ============================================================================== > > --- cfe/trunk/docs/LibFormat.rst (added) > > +++ cfe/trunk/docs/LibFormat.rst Wed Jan 9 15:49:28 2013 > > @@ -0,0 +1,56 @@ > > +========= > > +LibFormat > > +========= > > + > > +LibFormat is a library that implements automatic source code formatting > based > > +on Clang. This documents describes the LibFormat interface and design > as well > > +as some basic style discussions. > > + > > +If you just want to use `clang-format` as a tool or integrated into an > editor, > > +checkout :doc:`ClangFormat`. > > + > > +Design > > +------ > > + > > +FIXME: Write up design. > > + > > + > > +Interface > > +--------- > > + > > +The core routine of LibFormat is ``reformat()``: > > + > > +.. code-block:: c++ > > + > > + tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex, > > + SourceManager &SourceMgr, > > + std::vector<CharSourceRange> Ranges); > > + > > +This reads a token stream out of the lexer ``Lex`` and reformats all > the code > > +ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made > during > > +formatting. A list of options can be found under :ref:`style-options`. > > + > > + > > +.. _style-options: > > + > > +Style Options > > +------------- > > + > > +The style options describe specific formatting options that can be used > in > > +order to make `ClangFormat` comply with different style guides. > Currently, > > +two style guides are hard-coded: > > + > > +.. code-block:: c++ > > + > > + /// \brief Returns a format style complying with the LLVM coding > standards: > > + /// http://llvm.org/docs/CodingStandards.html. > > + FormatStyle getLLVMStyle(); > > + > > + /// \brief Returns a format style complying with Google's C++ style > guide: > > + /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml. > > + FormatStyle getGoogleStyle(); > > + > > +These options are also exposed in the :doc:`standalone tools > <ClangFormat>` > > +through the `-style` option. > > + > > +In the future, we plan on making this configurable. > > > > Modified: cfe/trunk/docs/index.rst > > URL: > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index.rst?rev=172004&r1=172003&r2=172004&view=diff > > > ============================================================================== > > --- cfe/trunk/docs/index.rst (original) > > +++ cfe/trunk/docs/index.rst Wed Jan 9 15:49:28 2013 > > @@ -32,14 +32,24 @@ > > Tooling > > IntroductionToTheClangAST > > LibTooling > > + LibFormat > > ClangPlugins > > RAVFrontendAction > > LibASTMatchersTutorial > > LibASTMatchers > > - ClangTools > > HowToSetupToolingForLLVM > > JSONCompilationDatabase > > > > +Using Clang Tools > > +================= > > + > > +.. toctree:: > > + :maxdepth: 1 > > + > > + ClangTools > > + ClangCheck > > + ClangFormat > > + > > Design Documents > > ================ > > > > > > > > _______________________________________________ > > cfe-commits mailing list > > [email protected] > > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits >
_______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
