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