[cfe-commits] r172004 - in /cfe/trunk/docs: ClangCheck.rst ClangFormat.rst ClangTools.rst LibFormat.rst index.rst
Daniel Jasper
djasper at google.com
Wed Jan 9 13:49:29 PST 2013
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
+
+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
================
More information about the cfe-commits
mailing list