OCLint
==============

An oclint test analyzes the translation unit's source code and enforces the predefined rules.
Each translation unit requires its own set of rules.
If the analyzed code violates at least one rule, the test is failed, and feedback on what rules have been violated is given.
Otherwise, feedback that the oclint test has been passed successfully is given.
The tool `OCLint <https://docs.oclint.org/en/stable>`_ is used to perform the analysis for this test case.

In addition to the configuration options presented in :doc:`test_definition_file` the following attributes are available:

- :ref:`suppress_line`: allow/disallow comments to suppress the analysis of the commented line.
- :ref:`suppress_range`: allow/disallow annotations to suppress the analysis.
- :ref:`disable_rules`: use all rules except for the rules given in this array.
- :ref:`apply_rules`: only use the rules given in this array.

.. note::
    For the oclint analysis the ``NDEBUG`` flag is always set during OCLint's the integrated compilation step in order to disable the analysis of ``assert`` statements.

Attribute details
--------------------------

Details on the additional configuration options for oclint tests are given in the following sections.

.. _suppress_line:

``suppress_line``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This rule indicates whether students are allowed to suppress OCLint warnings using the ``//!OCLint`` comment.

**Possible values:**

- ``true``: the suppression of OCLint warnings using the ``//!OCLint`` comment is allowed.
- ``false`` *(default)*: the suppression of OCLint warnings using the ``//!OCLint`` comment is not allowed.

Example:

.. code-block:: yaml

    suppress_line: true

If suppression of warnings is allowed all warnings generated by a line of code can be suppressed as follows:

.. code-block:: c

    void a() {
        int unusedLocalVariable; //!OCLint
    }

See `!OCLint Comment <https://docs.oclint.org/en/stable/howto/suppress.html#oclint-comment>`_ in the OCLint documentation for further details and examples.

.. _suppress_range:

``suppress_range``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This rule indicates whether students are allowed to suppress OCLint rules using annotations.

**Possible values:**

- ``true``: the suppression of OCLint rules using annotations is allowed.
- ``false`` *(default)*:  the suppression of OCLint rules using annotations is not allowed.

Example:

.. code-block:: yaml

    suppress_range: true

If suppression of rules is allowed all rules in the annotated scope are suppressed as follows:

.. code-block:: c

    __attribute__((annotate("oclint:suppress")))

See `Annotations <https://docs.oclint.org/en/stable/howto/suppress.html#annotations>`_ in the OCLint documentation for further details and examples.


.. _disable_rules:

``disable_rules``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Array indicating the OCLint rules that should not be applied to the analyzed translation unit.

**Possible values:**

All rules defined in the `Rule Index <https://docs.oclint.org/en/stable/rules/index.html#rule-index>`_ of the OCLint documentation.
The rules have to be written as given in the referenced rule index.

Example:

.. code-block:: yaml

    disable_rules:
      - ShortVariableName
      - UselessParentheses


.. _apply_rules:

``apply_rules``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Array indicating the OCLint rules that be applied to the analyzed translation unit.

**Possible values:**

All rules defined in the `Rule Index <https://docs.oclint.org/en/stable/rules/index.html#rule-index>`_ of the OCLint documentation.
The rules have to be written as given in the referenced rule index.

Example:

.. code-block:: yaml

    apply_rules:
      - GotoStatement
      - EmptyElseBlock
      - LongVariableName
      - LongLine


Example code structure test definitions:
----------------------------------------

In this section, a few examples for oclint test definitions are given.

**Example 1:** select all applied rules by hand.

.. code-block:: yaml
    :linenos:

    version: "0.0"
    translation_unit: hello_world.c
    tests:
      - type: oclint
        name: Linter
        apply_rules:
          - GotoStatement
          - EmptyElseBlock
          - LongVariableName
          - LongLine

**Example 2:** select all applied rules by hand and allow students to disable rules.

.. code-block:: yaml

    version: "0.0"
    translation_unit: hello_world.c
    tests:
      - type: oclint
        name: Linter
        suppress_line: true
        suppress_range: true
        apply_rules:
          - GotoStatement
          - EmptyElseBlock
          - LongVariableName
          - LongLine


**Example 3:** disable selected rules and allow students to disable rules with line comments only.

.. code-block:: yaml

    version: "0.0"
    translation_unit: hello_world.c
    tests:
      - type: oclint
        name: Linter
        suppress_line: true
        disable_rules:
          - BitwiseOperatorInConditional
          - MissingBreakInSwitchStatement
          - UselessParentheses
          - HighCyclomaticComplexity
          - HighNPathComplexity
          - HighNcssMethod
          - ShortVariableName
          - EmptyIfStatement
          - MissingDefaultStatement
          - UselessParentheses