/****************************************************************************
**
** Copyright (C) 2022 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/

/*!
//! [clang format]

    \section2 Automatic Formatting and Indentation

    The Clang Format plugin uses the
    \l{https://clang.llvm.org/docs/LibFormat.html}{LibFormat}
    library for automatic formatting and indentation.

    To enable the plugin, select \uicontrol Help > \uicontrol {About Plugins} >
    \uicontrol {C++} > \uicontrol {ClangFormat}. Then select
    \uicontrol {Restart Now} to restart \QC and load the plugin.

    \note If you enable the plugin, do not use the \l{Beautifying Source Code}
    {Beautifier}, because combining the two can provide unexpected results.

    You can use Clang Format to enforce a coding style for a project or the
    whole organization. Create a \c {.clang-format} file that contains the
    \l{https://clang.llvm.org/docs/ClangFormatStyleOptions.html}
    {Clang Format Style Options} to use and save it in the root folder of the
    project or one of its parent folders. The plugin searches for the Clang
    format file recursively from the directory that contains the source file
    up to the file system root.

    To specify global settings for automatic formatting and indentation, you
    must copy the built-in settings and edit the copy:

    \list 1
       \li Select \uicontrol Tools > \uicontrol Options > \uicontrol {C++} >
            \uicontrol Edit > \uicontrol {Copy Built-in Code Style} >
            \uicontrol {ClangFormat}.
            \image qtcreator-code-style-clang-format.png "C++ Clang Format options"
        \li Select the \uicontrol {Format instead of indenting} check box to
            use the \key {Ctrl+I} keyboard shortcut to format code instead of
            indenting it.
        \li Select the \uicontrol {Format while typing} check box to apply the
            formatting while you type code.
        \li Select the \uicontrol {Format edited code on file save} check box
            to apply the formatting to the edited code when you save the file.
        \li Select the \uicontrol {Override Clang Format configuration file}
            check box to create a local configuration file that overrides the
            one stored in the file system.
            \note This is not recommended, because it defeats the purpose of
            a Clang format file.
        \li To modify the values in the file, select them in the left-side
            column and enter the new values.
        \li To view examples of the new values in the right-hand column, select
            \uicontrol Apply.
    \endlist

    To override the \c {.clang-format} file for a project, select
    \uicontrol Projects > \uicontrol {Project Settings} >
    \uicontrol {Code Style} > \uicontrol Edit >
    \uicontrol {Copy Built-in Code Style} > \uicontrol {ClangFormat} >
    \uicontrol {Override Clang Format configuration file}.

    You can create \c {.clang-format} files that contain the configuration
    options of a certain predefined style from the command line. For example,
    to create a format file for the LLVM style, enter the following command:

    \badcode
    clang-format -style=llvm -dump-config > .clang-format
    \endcode

//! [clang format]
*/
