From 063f03c764146a1917510cdbf52eabcf52afae7f Mon Sep 17 00:00:00 2001 From: Pieter Hijma Date: Tue, 28 Oct 2025 15:32:21 +0100 Subject: [PATCH] Doc: Move doc comments in App::Expression Several doc comments in App/Expression.cpp are moved to header files. --- src/App/Expression.cpp | 162 ++++++------------------------------- src/App/Expression.h | 25 ++++++ src/App/ExpressionParser.h | 16 ++++ 3 files changed, 64 insertions(+), 139 deletions(-) diff --git a/src/App/Expression.cpp b/src/App/Expression.cpp index d87d381dae..6ff0880582 100644 --- a/src/App/Expression.cpp +++ b/src/App/Expression.cpp @@ -1012,7 +1012,7 @@ ExpressionPtr Expression::importSubNames(const std::map if(key.second.empty() || subNameMap.contains(key)) continue; std::string imported = PropertyLinkBase::tryImportSubName( - obj,key.second.c_str(),owner->getDocument(), nameMap); + obj, key.second.c_str(), owner->getDocument(), nameMap); if(!imported.empty()) subNameMap.emplace(std::move(key),std::move(imported)); } @@ -1212,14 +1212,6 @@ void UnitExpression::setQuantity(const Quantity &_quantity) } } -/** - * Set unit information. - * - * @param _unit A unit object - * @param _unitstr The unit expressed as a string - * @param _scaler Scale factor to convert unit into internal unit. - */ - void UnitExpression::setUnit(const Quantity &_quantity) { quantity = _quantity; @@ -1230,33 +1222,16 @@ void UnitExpression::setUnit(const Quantity &_quantity) } } -/** - * Simplify the expression. In this case, a NumberExpression is returned, - * as it cannot be simplified any more. - */ - Expression *UnitExpression::simplify() const { return new NumberExpression(owner, quantity); } -/** - * Return a string representation, in this case the unit string. - */ - -/** - * Return a string representation of the expression. - */ - void UnitExpression::_toString(std::ostream &ss, bool,int) const { ss << unitStr; } -/** - * Return a copy of the expression. - */ - Expression *UnitExpression::_copy() const { return new UnitExpression(owner, quantity, unitStr); @@ -1279,29 +1254,16 @@ NumberExpression::NumberExpression(const DocumentObject *_owner, const Quantity { } -/** - * Simplify the expression. For NumberExpressions, we return a copy(), as it cannot - * be simplified any more. - */ - Expression *NumberExpression::simplify() const { return copy(); } -/** - * Create and return a copy of the expression. - */ - Expression *NumberExpression::_copy() const { return new NumberExpression(owner, getQuantity()); } -/** - * Negate the stored value. - */ - void NumberExpression::negate() { setQuantity(-getQuantity()); @@ -1352,10 +1314,6 @@ OperatorExpression::~OperatorExpression() delete right; } -/** - * Determine whether the expression is touched or not, i.e relies on properties that are touched. - */ - bool OperatorExpression::isTouched() const { return left->isTouched() || right->isTouched(); @@ -1477,14 +1435,6 @@ Py::Object OperatorExpression::_getPyValue() const { return calc(this,op,left,right,false); } -/** - * Simplify the expression. For OperatorExpressions, we return a NumberExpression if - * both the left and right side can be simplified to NumberExpressions. In this case - * we can calculate the final value of the expression. - * - * @returns Simplified expression. - */ - Expression *OperatorExpression::simplify() const { Expression * v1 = left->simplify(); @@ -1500,12 +1450,6 @@ Expression *OperatorExpression::simplify() const return new OperatorExpression(owner, v1, op, v2); } -/** - * Create a string representation of the expression. - * - * @returns A string representing the expression. - */ - void OperatorExpression::_toString(std::ostream &s, bool persistent,int) const { bool needsParens; @@ -1607,22 +1551,11 @@ void OperatorExpression::_toString(std::ostream &s, bool persistent,int) const right->toString(s,persistent); } -/** - * A deep copy of the expression. - */ - Expression *OperatorExpression::_copy() const { return new OperatorExpression(owner, left->copy(), op, right->copy()); } -/** - * Return the operators priority. This is used to add parentheses where - * needed when creating a string representation of the expression. - * - * @returns The operator's priority. - */ - int OperatorExpression::priority() const { switch (op) { @@ -1849,13 +1782,6 @@ FunctionExpression::~FunctionExpression() } } -/** - * Determine whether the expressions is considered touched, i.e one or both of its arguments - * are touched. - * - * @return True if touched, false if not. - */ - bool FunctionExpression::isTouched() const { std::vector::const_iterator i = args.begin(); @@ -2657,12 +2583,6 @@ Py::Object FunctionExpression::_getPyValue() const { return evaluate(this,f,args); } -/** - * Try to simplify the expression, i.e calculate all constant expressions. - * - * @returns A simplified expression. - */ - Expression *FunctionExpression::simplify() const { size_t numerics = 0; @@ -2691,12 +2611,6 @@ Expression *FunctionExpression::simplify() const std::move(simplifiedArgs)); } -/** - * Create a string representation of the expression. - * - * @returns A string representing the expression. - */ - void FunctionExpression::_toString(std::ostream &ss, bool persistent,int) const { switch (f) { @@ -2847,12 +2761,6 @@ void FunctionExpression::_toString(std::ostream &ss, bool persistent,int) const ss << ')'; } -/** - * Create a copy of the expression. - * - * @returns A deep copy of the expression. - */ - Expression *FunctionExpression::_copy() const { std::vector::const_iterator i = args.begin(); @@ -2890,30 +2798,11 @@ VariableExpression::VariableExpression(const DocumentObject *_owner, const Objec VariableExpression::~VariableExpression() = default; -/** - * Determine if the expression is touched or not, i.e whether the Property object it - * refers to is touched(). - * - * @returns True if the Property object is touched, false if not. - */ - bool VariableExpression::isTouched() const { return var.isTouched(); } -/** - * Find the property this expression referse to. - * - * Unqualified names (i.e the name only without any dots) are resolved in the owning DocumentObjects. - * Qualified names are looked up in the owning Document. It is first looked up by its internal name. - * If not found, the DocumentObjects' labels searched. - * - * If something fails, an exception is thrown. - * - * @returns The Property object if it is derived from either PropertyInteger, PropertyFloat, or PropertyString. - */ - const Property * VariableExpression::getProperty() const { const Property * prop = var.getProperty(); @@ -2985,22 +2874,11 @@ void VariableExpression::_toString(std::ostream &ss, bool persistent,int) const ss << var.toString(); } -/** - * Simplify the expression. Simplification of VariableExpression objects is - * not possible (if it is instantiated it would be an evaluation instead). - * - * @returns A copy of the expression. - */ - Expression *VariableExpression::simplify() const { return copy(); } -/** - * Return a copy of the expression. - */ - Expression *VariableExpression::_copy() const { return new VariableExpression(owner, var); @@ -3201,10 +3079,6 @@ StringExpression::~StringExpression() { } } -/** - * Simplify the expression. For strings, this is a simple copy of the object. - */ - Expression *StringExpression::simplify() const { return copy(); @@ -3215,10 +3089,6 @@ void StringExpression::_toString(std::ostream &ss, bool,int) const ss << quote(text); } -/** - * Return a copy of the expression. - */ - Expression *StringExpression::_copy() const { return new StringExpression(owner, text); @@ -3548,9 +3418,10 @@ bool isModuleImported(PyObject *module) { } /** - * Error function for parser. Throws a generic Base::Exception with the parser error. + * @brief Error function for parser. + * + * @throws Base::Exception A generic parser error. */ - void ExpressionParser_yyerror(const char *errorinfo) { (void)errorinfo; @@ -3586,12 +3457,24 @@ double num_change(char* yytext,char dez_delim,char grp_delim) return ret_val; } -static Expression * ScanResult = nullptr; /**< The resulting expression after a successful parsing */ -static const App::DocumentObject * DocumentObject = nullptr; /**< The DocumentObject that will own the expression */ -static bool unitExpression = false; /**< True if the parsed string is a unit only */ -static bool valueExpression = false; /**< True if the parsed string is a full expression */ -static std::stack labels; /**< Label string primitive */ -static std::map registered_functions; /**< Registered functions */ +/// The resulting expression after a successful parsing. +static Expression* ScanResult = nullptr; + +/// The DocumentObject that will own the expression. +static const App::DocumentObject* DocumentObject = nullptr; + +/// Whether the parsed string is a unit only. +static bool unitExpression = false; + +/// Whether the parsed string is a full expression. +static bool valueExpression = false; + +/// Label string primitive. +static std::stack labels; + +/// Registered functions during parsing. +static std::map registered_functions; + static int last_column; static int column; @@ -3885,3 +3768,4 @@ bool ExpressionParser::isTokenAUnit(const std::string & str) #if defined(__clang__) # pragma clang diagnostic pop #endif + diff --git a/src/App/Expression.h b/src/App/Expression.h index 1b416c4ca8..ec9268596a 100644 --- a/src/App/Expression.h +++ b/src/App/Expression.h @@ -127,6 +127,14 @@ public: ~Expression() override; + /** + * @brief Check if the expression is touched. + * + * An expression is touched if one of the properties it references is + * touched. + * + * @return true if the expression is touched, false otherwise. + */ virtual bool isTouched() const { return false; } Expression * eval() const; @@ -138,6 +146,14 @@ public: Expression * copy() const; + /** + * @brief Get the operator priority. + * + * This is used to determine whether parentheses are needed when + * converting the expression to a string. + * + * @return The operator priority. + */ virtual int priority() const; void getIdentifiers(std::map &) const; @@ -164,6 +180,15 @@ public: bool adjustLinks(const std::set &inList); + /** + * @brief Simplify the expression. + * + * In contrast to @ref eval, which evaluates the expression to a value, + * this function simplifies the expression by computing all constant + * expressions. + * + * @return The simplified expression. + */ virtual Expression * simplify() const = 0; void visit(ExpressionVisitor & v); diff --git a/src/App/ExpressionParser.h b/src/App/ExpressionParser.h index 1cabea5ccb..c109862f33 100644 --- a/src/App/ExpressionParser.h +++ b/src/App/ExpressionParser.h @@ -143,6 +143,9 @@ public: Expression* simplify() const override; + /** + * @brief Negate the stored value. + */ void negate(); bool isInteger(long* v = nullptr) const; @@ -473,6 +476,19 @@ public: void setPath(const ObjectIdentifier& path); + /** + * @brief Find the property this expression referse to. + * + * Unqualified names (i.e the name only without any dots) are resolved in + * the owning DocumentObjects. Qualified names are looked up in the owning + * Document, first, by its internal name, then if not found, by the + * DocumentObjects' labels. + * + * @return The Property object if it is derived from either + * PropertyInteger, PropertyFloat, or PropertyString. + * + * @trhows Expression::Exception If the property cannot be resolved. + */ const App::Property* getProperty() const; void addComponent(Component* component) override;