AutosarC++18_03-A15.4.5

Checked exceptions that could be thrown from a function shall be specified together with the function declaration and they shall be identical in all function declarations and for all its overriders

Required inputs: IR, StaticSemanticAnalysis

Rationale

In C++ language, all exceptions are unchecked, because the compiler does not force to either handle the exception or specify it. Because dynamic-exception specification is obsolete and error prone, an alternative mechanism of specifying checked exceptions using C++ comments along with function declarations is used. It is a concept that is based on Java exception handling mechanism.

When analyzing a given function f, a static code analysis needs to analyze functions invoked by f and analyze if they throw any checked exceptions that are not caught by f and not listed by f in the function comment.

Exceptions

Within generic code, it is not generally possible to know what types of exceptions may be thrown from operations on template arguments, so a precise exception specification cannot be written. Therefore, this rule does not apply for templates.

Example
//% $Id: A15-4-5.cpp 309502 2018-02-28 09:17:39Z michal.szczepankiewicz $
#include <cstdint>
#include <stdexcept>

/// @checkedException
class CommunicationError : public std::exception {
  // Implementation
};
/// @checkedException
class BusError : public CommunicationError {
  // Implementation
};
/// @checkedException
class Timeout : public std::runtime_error {
public:
  using std::runtime_error::runtime_error;
  // Implementation
};
/// @throw CommunicationError Communication error
/// @throw BusError Bus error
/// @throw Timeout    On send timeout exception
void Send1(
    std::uint8_t *buffer,
    std::uint8_t bufferLength) noexcept(false) //    Compliant - All and only
                                               //   those checked exceptions
                                               //   that can be thrown are
                                               //   specified
{
  // ...
  throw CommunicationError();
  // ...
  throw BusError();
  // ...
  throw Timeout("Timeout reached");
  // ...
}
/// @throw CommunicationError Communication error
void Send2(
    std::uint8_t *buffer,
    std::uint8_t bufferLength) noexcept(false) //    Non-compliant - checked
                                               //   exceptions that can be
                                               //   thrown are missing from
                                               //   specification
{
  // ...
  throw CommunicationError();
  // ...
  throw Timeout("Timeout reached");
  // ...
}
class MemoryPartitioningError : std::exception {
  // Implementation
};
/// @throw CommunicationError Communication error
/// @throw BusError Bus error
/// @throw Timeout   On send timeout exception
/// @throw MemoryPartitioningError Memory partitioning error prevents message
/// from being sent.
void Send3(
    std::uint8_t *buffer,
    std::uint8_t bufferLength) noexcept(false) // Non-compliant - additional
                                               // checked exceptions are
                                               // specified
{
  // ...
  throw CommunicationError();
  // ...
  throw Timeout("Timeout reached");
  // ...
}
See Also
  • Effective Java 2nd Edition [14]: Item 62: Document all exceptions thrown by each method

Possible Messages

Key

Text

Severity

Disabled

differing_documented

Documented exceptions differ from overridden method.

None

False

document_exception

Document checked exception {} using {}.

None

False

superfluous_documented

Documented exceptions {} probably never thrown.

None

False

Options

autosar_exception_model

autosar_exception_model : str = '18_03'

The default model for what counts as an checked / unchecked exception.
 

exclude_exception_base_classes

exclude_exception_base_classes : set[bauhaus.analysis.config.QualifiedName] = set()

Exclude issues for the exception types mentioned in this set of qualified names. Also excludes classes derived from those class names as well as pointers or references to any of these class types.
 

ignore_definitions_if_declaration_documented

ignore_definitions_if_declaration_documented : bool = False

Instead of requiring the documentation to be repeated for every declaration (including definition), with this option set, the rule only checks the non-defining declarations if at least one non-defining declaration exists.
 

include_template_instances

include_template_instances : bool = False

If true, also analyse thrown exceptions for template instances. There will only be a single combined violation for all template instances, checking that the documented exceptions match the union of exceptions thrown by the template instances. This treatment corresponds to functions with function pointer arguments. For AUTOSAR compliance this option should be false. The AUTOSAR rule does not apply to templates, because a precise exception specification cannot be written.
 

match_qualified_name

match_qualified_name : bool = True

Matches the fully-qualified name when comparing documented exceptions with what can actually occur. If set to false, this rule will accept any suffix of the qualified name of an exception class as the documentation string.
 

throw_marker

throw_marker : str = '@throw'

The command to document an exception to be thrown.