From: Daniel Jasper Date: Wed, 9 Jan 2013 21:49:28 +0000 (+0000) Subject: Add documentation for clang-format. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6d5b57a5c7b05ac092b6a4b9704bea937cc3ba23;p=clang 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. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@172004 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/ClangCheck.rst b/docs/ClangCheck.rst new file mode 100644 index 0000000000..4650049b1f --- /dev/null +++ b/docs/ClangCheck.rst @@ -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 < 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 <> + (TypedefDecl 0x7ff3a302a410 <> __int128_t '__int128') + (TypedefDecl 0x7ff3a302a470 <> __uint128_t 'unsigned __int128') + (TypedefDecl 0x7ff3a302a830 <> __builtin_va_list '__va_list_tag [1]') + (FunctionDecl 0x7ff3a302a8d0 f 'void (void)' + (CompoundStmt 0x7ff3a302aa10 + (DeclStmt 0x7ff3a302a9f8 + (VarDecl 0x7ff3a302a980 a 'int' + (IntegerLiteral 0x7ff3a302a9d8 '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`. diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst new file mode 100644 index 0000000000..2fae3904d4 --- /dev/null +++ b/docs/ClangFormat.rst @@ -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 `) 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 is given, it reformats the file. If -i is specified together + with , the file is edited in-place. Otherwise, the result is + written to the standard output. + + USAGE: clang-format [options] [] + + OPTIONS: + -fatal-assembler-warnings - Consider warnings as error + -help - Display available options (-help-hidden for more) + -i - Inplace edit , if specified. + -length= - Format a range of this length, -1 for end of file. + -offset= - Format a range starting at this file offset. + -stats - Enable statistics output from program + -style= - 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 :pyf /clang-format.py + imap :pyf /clang-format.pyi + +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). diff --git a/docs/ClangTools.rst b/docs/ClangTools.rst index 3839e703db..8d5f10000c 100644 --- a/docs/ClangTools.rst +++ b/docs/ClangTools.rst @@ -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 @@ tools that very specifically compliment, and allow use and testing of ``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 ` and a :doc:`stand-alone tool +` 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 ================= diff --git a/docs/LibFormat.rst b/docs/LibFormat.rst new file mode 100644 index 0000000000..eacdc16145 --- /dev/null +++ b/docs/LibFormat.rst @@ -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 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 ` +through the `-style` option. + +In the future, we plan on making this configurable. diff --git a/docs/index.rst b/docs/index.rst index 4a20bb9fa6..66906e5aba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,14 +32,24 @@ Using Clang as a Library Tooling IntroductionToTheClangAST LibTooling + LibFormat ClangPlugins RAVFrontendAction LibASTMatchersTutorial LibASTMatchers - ClangTools HowToSetupToolingForLLVM JSONCompilationDatabase +Using Clang Tools +================= + +.. toctree:: + :maxdepth: 1 + + ClangTools + ClangCheck + ClangFormat + Design Documents ================