added @throws to documentation [skip ci]

firewave · firewave · commit 8173ff0d92f8 · 2025-12-15T12:46:55.000+01:00
diff --git a/lib/calculate.h b/lib/calculate.h
@@ -46,6 +46,9 @@ bool isZero(T x)
     return isEqual(x, T(0));
 }
 
+/**
+ * @throws InternalError thrown in case of unknown operator
+ */
 template<class R, class T>
 R calculate(const std::string& s, const T& x, const T& y, bool* error = nullptr)
 {
diff --git a/lib/checkleakautovar.h b/lib/checkleakautovar.h
@@ -119,7 +119,9 @@ class CPPCHECKLIB CheckLeakAutoVar : public Check {
     /** check for leaks in all scopes */
     void check();
 
-    /** check for leaks in a function scope */
+    /** check for leaks in a function scope
+     * @throws InternalError thrown if recursion cound is exceeded
+     */
     bool checkScope(const Token * startToken,
                     VarInfo &varInfo,
                     std::set<int> notzero,
diff --git a/lib/checkother.h b/lib/checkother.h
@@ -195,6 +195,9 @@ class CPPCHECKLIB CheckOther : public Check {
 
     void checkModuloOfOne();
 
+    /**
+    * @throws InternalError thrown if largest union member could not be found
+    */
     void checkUnionZeroInit();
 
     void checkOverlappingWrite();
diff --git a/lib/cppcheck.cpp b/lib/cppcheck.cpp
@@ -424,6 +424,9 @@ static std::string detectPython(const CppCheck::ExecuteCmdFn &executeCommand)
     return "";
 }
 
+/**
+ * @throws InternalError thrown when execution fails
+ */
 static std::vector<picojson::value> executeAddon(const AddonInfo &addonInfo,
                                                  const std::string &defaultPythonExe,
                                                  const std::string &file,
diff --git a/lib/symboldatabase.h b/lib/symboldatabase.h
@@ -777,6 +777,9 @@ class CPPCHECKLIB Function {
     nonneg int initializedArgCount() const {
         return initArgCount;
     }
+    /**
+    * @throws InternalError thrown on unrecognized lambda
+    */
     void addArguments(const Scope *scope);
 
     /** @brief check if this function is virtual in the base classes */
@@ -1438,6 +1441,9 @@ class CPPCHECKLIB SymbolDatabase {
     friend class Function;
 
     // Create symboldatabase...
+    /**
+    * @throws InternalError thrown on unhandled code
+    */
     void createSymbolDatabaseFindAllScopes();
     void createSymbolDatabaseClassInfo();
     void createSymbolDatabaseVariableInfo();
@@ -1461,6 +1467,9 @@ class CPPCHECKLIB SymbolDatabase {
     void addClassFunction(Scope *&scope, const Token *&tok, const Token *argStart);
     RET_NONNULL static Function *addGlobalFunctionDecl(Scope*& scope, const Token* tok, const Token *argStart, const Token* funcStart);
     Function *addGlobalFunction(Scope*& scope, const Token*& tok, const Token *argStart, const Token* funcStart);
+    /**
+    * @throws InternalError thrown on unrecognized function
+    */
     void addNewFunction(Scope *&scope, const Token *&tok);
     bool isFunction(const Token *tok, const Scope* outerScope, const Token *&funcStart, const Token *&argStart, const Token*& declEnd) const;
     const Type *findTypeInNested(const Token *startTok, const Scope *startScope) const;
@@ -1485,6 +1494,7 @@ class CPPCHECKLIB SymbolDatabase {
     void validateExecutableScopes() const;
     /**
      * @brief Check variable list, e.g. variables w/o scope
+     * @throws InternalError thrown on variable without scope
      */
     void validateVariables() const;
 
diff --git a/lib/templatesimplifier.h b/lib/templatesimplifier.h
@@ -150,10 +150,11 @@ class CPPCHECKLIB TemplateSimplifier {
         TokenAndName(Token *token, std::string scope);
         /**
          * Constructor used for declarations.
-         * \param token template declaration token "template < ... >"
-         * \param scope full qualification of template(scope)
-         * \param nameToken template name token "template < ... > class name"
-         * \param paramEnd template parameter end token ">"
+         * @param token template declaration token "template < ... >"
+         * @param scope full qualification of template(scope)
+         * @param nameToken template name token "template < ... > class name"
+         * @param paramEnd template parameter end token ">"
+         * @throws InternalError thrown on template issues
          */
         TokenAndName(Token *token, std::string scope, const Token *nameToken, const Token *paramEnd);
         TokenAndName(const TokenAndName& other);
@@ -319,6 +320,7 @@ class CPPCHECKLIB TemplateSimplifier {
      * @param tok start token
      * @return true if modifications to token-list are done.
      *         false if no modifications are done.
+     * @throws InternalError thrown on dvision by zero in template instantiation
      */
     static bool simplifyNumericCalculations(Token *tok, bool isTemplate = true);
 
@@ -459,7 +461,9 @@ class CPPCHECKLIB TemplateSimplifier {
      */
     static bool removeTemplate(Token *tok, std::map<Token*, Token*>* forwardDecls = nullptr);
 
-    /** Syntax error */
+    /** Syntax error
+     * @throws InternalError thrown unconditionally
+     */
     NORETURN static void syntaxError(const Token *tok);
 
     static bool matchSpecialization(
diff --git a/lib/token.cpp b/lib/token.cpp
@@ -403,6 +403,9 @@ void Token::replace(Token *replaceThis, Token *start, Token *end)
     delete replaceThis;
 }
 
+/**
+ * @throws InternalError thrown on unexpected command or missing varid with %varid%
+ */
 static
 #if defined(__GNUC__)
 // GCC does not inline this by itself
diff --git a/lib/token.h b/lib/token.h
@@ -902,6 +902,9 @@ class CPPCHECKLIB Token {
         return tok;
     }
 
+    /**
+     * @throws InternalError thrown if index if out of range
+     */
     template<class T, REQUIRES("T must be a Token class", std::is_convertible<T*, const Token*> )>
     static T *linkAtImpl(T *thisTok, int index)
     {
@@ -1532,7 +1535,9 @@ class CPPCHECKLIB Token {
     }
 
     /** Updates internal property cache like _isName or _isBoolean.
-        Called after any mStr() modification. */
+        Called after any mStr() modification.
+        @throws InternalError thrown if a bool literal has a varid
+     */
     void update_property_info();
 
     /** Update internal property cache about isStandardType() */
@@ -1548,6 +1553,9 @@ class CPPCHECKLIB Token {
 public:
     void astOperand1(Token *tok);
     void astOperand2(Token *tok);
+    /**
+     * @throws InternalError thrown on cyclic dependency
+     */
     void astParent(Token* tok);
 
     Token * astOperand1() {
@@ -1602,6 +1610,9 @@ class CPPCHECKLIB Token {
         return ret;
     }
 
+    /**
+     * @throws InternalError thrown if start or end cannot be found
+     */
     std::pair<const Token *, const Token *> findExpressionStartEndTokens() const;
 
     /**
diff --git a/lib/tokenize.cpp b/lib/tokenize.cpp
@@ -669,6 +669,9 @@ namespace {
             return mNameToken ? mNameToken->str() : "";
         }
 
+        /**
+         * @throws InternalError thrown if simplification failed
+         */
         void replace(Token* tok) {
             if (tok == mNameToken)
                 return;
@@ -4234,6 +4237,9 @@ void VariableMap::addVariable(const std::string& varname, bool globalNamespace)
     it->second = ++mVarId;
 }
 
+/**
+ * @throws Token* thrown when closing brackets are missing
+ */
 static bool setVarIdParseDeclaration(Token*& tok, const VariableMap& variableMap, bool executableScope, Standards::cstd_t cStandard)
 {
     const Token* const tok1 = tok;
diff --git a/lib/tokenize.h b/lib/tokenize.h
@@ -376,17 +376,25 @@ class CPPCHECKLIB Tokenizer {
 
 public:
 
-    /** Syntax error */
+    /** Syntax error
+     * @throws InternalError thrown unconditionally
+     */
     NORETURN void syntaxError(const Token *tok, const std::string &code = "") const;
 
-    /** Syntax error. Unmatched character. */
+    /** Syntax error. Unmatched character.
+     * @throws InternalError thrown unconditionally
+     */
     NORETURN void unmatchedToken(const Token *tok) const;
 
 private:
-    /** Syntax error. C++ code in C file. */
+    /** Syntax error. C++ code in C file.
+     * @throws InternalError thrown unconditionally
+     */
     NORETURN void syntaxErrorC(const Token *tok, const std::string &what) const;
 
-    /** Warn about unknown macro(s), configuration is recommended */
+    /** Warn about unknown macro(s), configuration is recommended #
+     * @throws InternalError thrown unconditionally
+     */
     NORETURN void unknownMacroError(const Token *tok1) const;
 
     void unhandledCharLiteral(const Token *tok, const std::string& msg) const;
diff --git a/lib/tokenlist.cpp b/lib/tokenlist.cpp
@@ -658,6 +658,9 @@ static bool isQualifier(const Token* tok)
     return Token::Match(tok, "{|;");
 }
 
+/**
+ * @throws InternalError thrown if maximum AST depth is exceeded
+ */
 static void compileUnaryOp(Token *&tok, AST_state& state, void (*f)(Token *&tok, AST_state& state))
 {
     Token *unaryop = tok;
@@ -694,6 +697,9 @@ static void skipGenericType(Token *&tok)
     }
 }
 
+/**
+ * @throws InternalError thrown if maximum AST depth is exceeded
+ */
 static void compileBinOp(Token *&tok, AST_state& state, void (*f)(Token *&tok, AST_state& state))
 {
     Token *binop = tok;
@@ -730,6 +736,9 @@ static void compileBinOp(Token *&tok, AST_state& state, void (*f)(Token *&tok, A
 
 static void compileExpression(Token *&tok, AST_state& state);
 
+/**
+ * @throws InternalError thrown if unexpected tokens are encountered
+ */
 static void compileTerm(Token *&tok, AST_state& state)
 {
     if (!tok)
@@ -929,6 +938,9 @@ static bool isPrefixUnary(const Token* tok, bool cpp)
     return tok->strAt(-1) == ")" && iscast(tok->linkAt(-1), cpp);
 }
 
+/**
+ * @throws InternalError thrown if unexpected tokens are encountered
+ */
 static void compilePrecedence2(Token *&tok, AST_state& state)
 {
     auto doCompileScope = [&](const Token* tok) -> bool {
@@ -1419,6 +1431,9 @@ static void compileComma(Token *&tok, AST_state& state)
     }
 }
 
+/**
+ * @throws InternalError thrown if maximum AST depth is exceeded
+ */
 static void compileExpression(Token *&tok, AST_state& state)
 {
     if (state.depth > AST_MAX_DEPTH)
@@ -1555,6 +1570,9 @@ static Token *skipMethodDeclEnding(Token *tok)
     return nullptr;
 }
 
+/**
+ * @throws InternalError thrown in case of syntax error
+ */
 static Token * createAstAtToken(Token *tok)
 {
     const bool cpp = tok->isCpp();
diff --git a/lib/tokenlist.h b/lib/tokenlist.h
@@ -168,12 +168,13 @@ class CPPCHECKLIB TokenList {
 
     /**
      * Create abstract syntax tree.
+     * @throws InternalError thrown if encountering an infinite loop in AST creation
      */
     void createAst() const;
 
     /**
      * Check abstract syntax tree.
-     * Throws InternalError on failure
+     * @throws InternalError thrown if validation fails
      */
     void validateAst(bool print) const;
 
diff --git a/lib/valueflow.cpp b/lib/valueflow.cpp
@@ -3789,6 +3789,9 @@ static void valueFlowSymbolicInfer(const SymbolDatabase& symboldatabase, const S
     }
 }
 
+/**
+ * @throws InternalError thrown if start token precedes end token
+ */
 template<class ContainerOfValue>
 static void valueFlowForwardConst(Token* start,
                                   const Token* end,

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,9 @@ bool isZero(T x)`
`46`	`46`	`return isEqual(x, T(0));`
`47`	`47`	`}`
`48`	`48`
	`49`	`+/**`
	`50`	`+ * @throws InternalError thrown in case of unknown operator`
	`51`	`+ */`
`49`	`52`	`template<class R, class T>`
`50`	`53`	`R calculate(const std::string& s, const T& x, const T& y, bool* error = nullptr)`
`51`	`54`	`{`
Original file line number	Diff line number	Diff line change
`@@ -424,6 +424,9 @@ static std::string detectPython(const CppCheck::ExecuteCmdFn &executeCommand)`
`424`	`424`	`return "";`
`425`	`425`	`}`
`426`	`426`
	`427`	`+/**`
	`428`	`+ * @throws InternalError thrown when execution fails`
	`429`	`+ */`
`427`	`430`	`static std::vector<picojson::value> executeAddon(const AddonInfo &addonInfo,`
`428`	`431`	`const std::string &defaultPythonExe,`
`429`	`432`	`const std::string &file,`
Original file line number	Diff line number	Diff line change
`@@ -403,6 +403,9 @@ void Token::replace(Token replaceThis, Token start, Token *end)`
`403`	`403`	`delete replaceThis;`
`404`	`404`	`}`
`405`	`405`
	`406`	`+/**`
	`407`	`+ * @throws InternalError thrown on unexpected command or missing varid with %varid%`
	`408`	`+ */`
`406`	`409`	`static`
`407`	`410`	`#if defined(__GNUC__)`
`408`	`411`	`// GCC does not inline this by itself`
Original file line number	Diff line number	Diff line change
`@@ -669,6 +669,9 @@ namespace {`
`669`	`669`	`return mNameToken ? mNameToken->str() : "";`
`670`	`670`	`}`
`671`	`671`
	`672`	`+ /**`
	`673`	`+ * @throws InternalError thrown if simplification failed`
	`674`	`+ */`
`672`	`675`	`void replace(Token* tok) {`
`673`	`676`	`if (tok == mNameToken)`
`674`	`677`	`return;`
`@@ -4234,6 +4237,9 @@ void VariableMap::addVariable(const std::string& varname, bool globalNamespace)`
`4234`	`4237`	`it->second = ++mVarId;`
`4235`	`4238`	`}`
`4236`	`4239`
	`4240`	`+/**`
	`4241`	`+ * @throws Token* thrown when closing brackets are missing`
	`4242`	`+ */`
`4237`	`4243`	`static bool setVarIdParseDeclaration(Token*& tok, const VariableMap& variableMap, bool executableScope, Standards::cstd_t cStandard)`
`4238`	`4244`	`{`
`4239`	`4245`	`const Token* const tok1 = tok;`