[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 14:03:17 PST 2013
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 <thakis at chromium.org> wrote:
> On Wed, Jan 9, 2013 at 1:49 PM, Daniel Jasper <djasper at google.com> 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
> > cfe-commits at cs.uiuc.edu
> > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130109/642d1eef/attachment.html>
More information about the cfe-commits
mailing list