// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-axivion.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title View Axivion static code analysis results

    Connect to an Axivion dashboard server from \QC to view results of code
    analysis.

    \note Enable the Axivion plugin to use it. To use the plugin, you must be
    connected to an Axivion dashboard server.

    \section1 View inline annotations in editor

    The editor shows found issues as inline annotations only if the project is
    configured with a path mapping.
    Hover over an annotation to bring up a tooltip with a short
    description of the issue.

    \image {qtcreator-axivion-annotation.webp} {Annotation popup}

    Select \inlineimage {icons/info.png} {Show Issues in Editor} to view detailed
    information about the issue in the \uicontrol {Issue Details} view.

    \image {qtcreator-axivion-view-rule.webp} {Issue Details view}

    To hide inline annotations, go to \uicontrol Analyze > \uicontrol Axivion
    and clear \inlineimage {icons/warning.png} {Show Issue Annotations Inline}.

    \section1 View issues

    To inspect issues found during the analyses:

    \list 1
        \li To go to the \uicontrol Axivion view:
            \image {qtcreator-axivion-issue-search.webp} {Issues in Axivion view}
            \list
                \li Go to \uicontrol Analyze > \uicontrol Axivion.
                \li In the mode selector, select \uicontrol Debug >
                    \uicontrol Axivion.
                \li Switch to the \uicontrol Debug mode, and select
                    \uicontrol Axivion in the debugger toolbar.
            \endlist
        \li Select a dashboard and a project.
        \li Select the icon of an issue type.
    \endlist

    \section1 Sort issues

    To sort the list of issues:
    \list
        \li For ascending order, select the up arrow in the column heading.
        \li For descending order, select the down arrow in the column heading.
        \li To remove sorting, toggle the arrow.
        \li To cycle through the sort options, select the column heading.
        \li To sort several columns, hold \key Shift while setting the
        sort order.
        The most recently sorted column is appended to the list of
        columns to sort.
        \li To clear sort options, toggle the sort order of a column
        without holding \key Shift.
    \endlist

    To refresh the list, select \imagereload (\uicontrol {Reload}).

    To get help, select \inlineimage {icons/info.png} {Show Online Filter Help}.

    \section1 Issue types

    Axivion looks for the following types of issues in the selected project:

    \table
    \header
        \li Icon
        \li Type
        \li Description
    \row
        \li \inlineimage {icons/axivion-av.png} {AV}
        \li \uicontrol AV
        \li Architecture violations, such as hidden dependencies.
    \row
        \li \inlineimage {icons/axivion-cl.png} {CL}
        \li \uicontrol CL
        \li Clones, such as duplicates and similar pieces of code.
    \row
        \li \inlineimage {icons/axivion-cy.png} {CY}
        \li \uicontrol CY
        \li Cyclic dependencies, such as call, component, and include cycles.
    \row
        \li \inlineimage {icons/axivion-de.png} {DE}
        \li \uicontrol DE
        \li Dead entities are callable entities in the source code that cannot
            be reached from the entry points of the system under analysis.
    \row
        \li \inlineimage {icons/axivion-mv.png} {MV}
        \li \uicontrol MV
        \li Violations of metrics based on lines and tokens,
            nesting, cyclomatic complexity, control flow, and so on.
    \row
        \li \inlineimage {icons/axivion-sv.png} {SV}
        \li \uicontrol SV
        \li Style violations, such as deviations from the naming
            or coding conventions.
    \endtable

    \section1 Filter issues

    To filter issues, select:

    \list
        \li The icon of an issue type.
        \li Two analyzed versions to compare. Select \uicontrol EMPTY to see
            issues from the version you select in the right-side version box.
        \li \inlineimage {icons/arrowup.png} {Added Issues} to see only added
            issues.
        \li \inlineimage {icons/arrowdown.png} {Removed Issues} to see only
            removed issues.
        \li The owner of the issue. Select \uicontrol ANYBODY to see all issues,
            \uicontrol NOBODY to see issues that are not associated with a user,
            or a user name to see issues owned by a particular user.
        \li Path patterns to show issues in the files in the directories that
            match the pattern.
    \endlist

    Select \inlineimage {icons/filtericon.png} {Filter} for a column to
    set or clear the filter expression for the column.

    The information you see depends on the issue type. Select an issue
    to see more information about it in the \uicontrol {Issue Details} view.
    Double-click an issue to see the code that causes the issue inside the
    editor.

    To show inline issues, select
    \inlineimage {icons/location.png} {Show Issues in Editor}.

    \section1 Jump to issues in the editor

    Typically, the details for cycles and clones show several paths. To view the
    issues in the editor:

    \list
        \li Select a location column (that shows a file or line) to open the
            respective location (if it can be found).
        \li Select other columns to open the first link in the issue details.
            Usually, it leads to the \uicontrol {Left location} or
            \uicontrol {Source location}.
    \endlist

    The easiest way to jump to the \uicontrol {Right location} is to
    select the link in the details or in the \uicontrol {Right Path}
    or \uicontrol {Target Path} column.

    If there is no valid mapping configured for the current selected project
    you will be prompted to set up a valid path mapping as jumping to the
    issue relies on having a valid path mapping configured.

    \sa {Connect to Axivion dashboard servers},
    {Local analysis with Axivion}{Local Analysis},
    {Enable and disable plugins},{Analyze}{How To: Analyze}, {Analyzers},
    {Analyzing code}
*/

/*!
    \page creator-axivion-localanalysis.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Local analysis with Axivion

    You can perform local analysis for projects you are connected to on a dashboard.
    In the issue table, select the respective dashboard and project.
    You need to have the Axivion Suite set up locally and a valid licence.

    To set up a local build for the active project inside the Axivion view:
    \image {qtcreator-axivion-localbuild.webp} {Local Build dialog}
    \list 1
    \li Select \inlineimage {icons/ax-localbuild.png}{Local Build} in the issue
    table.

    \li Select the Axivion Suite base directory in
    \uicontrol {Axivion Suite Installation Directory}.

    \li Enter the command or choose a script or the respective JSON file holding
    the Axivion configuration.

    \li Select the build type from \uicontrol {Build Type}. You may choose either
    a clean build or an incremental build.

    \li Select \uicontrol {Start Local Build} to perform the build with the given
    parameters.
    \endlist

    View running and finished local builds in \uicontrol {Local Analyses Progress}.

    \image {qtcreator-axivion-localbuild-progress.webp} {Local Analyses Progress}

    Right-click a local build to cancel a running build from the context menu.
    To inspect the output of the local build, double-click or select
    \uicontrol {Show Build Output} from the context menu. This opens the
    \uicontrol {Local Analyses Output} view, which provides the output for
    running or finished local analyses.
    Select \uicontrol {Remove All Finished} to remove the local builds that
    have finished already from the local build progress.
    This also removes the respective output from the
    \uicontrol {Local Analyses Output} view.

    \note If a previous run exists, starting a local analysis will reuse
    its progress items and output view.

    \section1 Local dashboard

    If the current selected project has a local build present, you may see
    its result by switching to the local dashboard view.

    Select \inlineimage {icons/ax-dashboard.png}{Local Dashboard} to do so.
    This starts the local dashboard and switches the issue table to display
    the latest results.

    Select \uicontrol {Local Dashboard} again to switch back to the global
    dashboard.

    Information about using the global dashboard applies to the local
    dashboard as well (issue type selection, filtering), but you have only
    a limited version selection.

    In \uicontrol {Version}, you can switch between the reference version
    of the global dashboard and the local dashboard results.
    Depending on the local build result you may limit the issue table to
    local issues or changed issues.

    \section1 Single file analysis

    To check whether your changes fix style issues or cause new ones, analyze
    a single file.

    To start a  single file analysis, go to
    \uicontrol Analyze > \uicontrol {Single File Analysis} or use the
    respective item inside the context menu of the file's editor.

    \image {qtcreator-axivion-startsfa.webp} {Single File Analysis dialog}

    In \uicontrol {BAUHAUS_CONFIG Directory}, specify the directory containing the
    Axivion configuration for this project.
    In \uicontrol {Analysis Command}, specify a command performing the build and the
    analysis.

    \note The analysis command usually is a call to \c build_compile_commands provided
    by the Axivion suite in use, but may also be a script file consisting of commands
    to build the respective file using \c cafeCC and analyze it.
    \c build_compile_commands can make use of a generated \c compile_commands.json file
    representing the build instructions of the project.
    For more information, see \l {Use compilation databases}.
    Put more complex commands into a script file to set up a special environment,
    for example.

    \note For more information about the commands and creating the script file,
    see \c {IDE Integration} and \c {Local Analyses} in the official Axivion documentation.

    You can see the progress of a running single file analysis in
    \uicontrol {Local Analyses Progress}. It will have the prefix \c {SFA:}.

    When the single file analysis finishes, additional color-coded line markers might
    be added to the opened file. Color-coded line markers originate from a single
    file analysis while others where fetched from the global dashboard.
    In case of a failed analysis, you can inspect the Axivion log or the build log,
    similar to local builds in general.

    \sa {Connect to Axivion dashboard servers},
    {View Axivion static code analysis results},
    {Enable and disable plugins}, {Analyze}{How To: Analyze}, {Analyzers},
    {Analyzing code}
*/

/*!
    \page creator-preferences-axivion.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Connect to Axivion dashboard servers

    You can connect to an Axivion dashboard server and map dashboard projects to
    local projects.

    \note Enable the Axivion plugin to use it.

    To connect to an Axivion dashboard server:

    \list 1
        \li Go to \preferences > \uicontrol Analyzer > \uicontrol Axivion.
            \image {qtcreator-preferences-axivion.webp} {Axivion tab in Analyzer preferences}
        \li Select \uicontrol Add to add a new connection to an Axivion
            dashboard server or \uicontrol Edit to change an existing connection:
            \image {qtcreator-edit-dashboard-configuration.webp} {Edit Dashboard Configuration dialog}
            \list
                \li In \uicontrol {Dashboard URL}, enter the URL of the server.
                \li Select \uicontrol {Anonymous authentication} to use anonymous
                    authentication.
                \li In \uicontrol Username, enter the username to access the server.
            \endlist
    \endlist

    The first time you access the server, you must enter the password that
    matches the username. It is stored safely in your keychain that is provided
    by the OS for later use.

    Select \uicontrol {Highlight marks} to highlight found issues on the
    scrollbar in the editor.

    Select \uicontrol Remove to remove the current selected connection to an
    Axivion dashboard server.

    \section1 Map paths

    Projects on the dashboard might have subprojects that also appear on the
    dashboard because they are analyzed separately.

    To map dashboard projects to local projects:

    \list 1
        \li In \uicontrol {Path Mapping}, select \uicontrol Add.
        \li In \uicontrol {Project name}, enter the project name on the dashboard.
        \li In \uicontrol {Analysis path}, enter the path to the analysis of a
            subproject. You need this only to map analyses of subprojects.
        \li In \uicontrol {Local path}, enter the path to the project on the
            computer.
    \endlist

    \section1 Local analyses

    To perform local analyses, specify additional settings.

    In \uicontrol {Axivion Suite path}, enter the path to the locally installed
    Axivion Suite.

    In \uicontrol {BAUHAUS_PYTHON}, enter the path to the python executable to be
    used by the local analysis if it cannot be found automatically.

    In \uicontrol {JAVA_HOME}, enter the path to a Java runtime or Java development
    kit if it cannot be found automatically.

    Select \uicontrol {Save all open files before starting an analysis} to
    automatically save files opened inside the editor before starting an analysis.

    \sa {Enable and disable plugins}, {View Axivion static code analysis results},
    {Local analysis with Axivion}{Local Analysis}, {Analyzing code}
*/
