From ee538f707ffb66345ef56968036b7af28f04ce98 Mon Sep 17 00:00:00 2001 From: Pieter Hijma Date: Tue, 28 Oct 2025 15:45:40 +0100 Subject: [PATCH] Doc: Move doc comments in PropertyExpressionEngine Several doc comments in App/PropertyExpressionEngine.cpp are moved to header files. --- src/App/PropertyExpressionEngine.cpp | 103 +------------------------ src/App/PropertyExpressionEngine.h | 110 +++++++++++++++++++++++++-- 2 files changed, 108 insertions(+), 105 deletions(-) diff --git a/src/App/PropertyExpressionEngine.cpp b/src/App/PropertyExpressionEngine.cpp index 241a93ead7..3f10e2133b 100644 --- a/src/App/PropertyExpressionEngine.cpp +++ b/src/App/PropertyExpressionEngine.cpp @@ -99,28 +99,13 @@ struct PropertyExpressionEngine::Private TYPESYSTEM_SOURCE(App::PropertyExpressionEngine, App::PropertyExpressionContainer) -/** - * @brief Construct a new PropertyExpressionEngine object. - */ - PropertyExpressionEngine::PropertyExpressionEngine() : validator(0) {} -/** - * @brief Destroy the PropertyExpressionEngine object. - */ - PropertyExpressionEngine::~PropertyExpressionEngine() = default; -/** - * @brief Estimate memory size of this property. - * - * \fixme Should probably return something else than 0. - * - * @return Size of object. - */ - +// fixme Should probably return something else than 0. unsigned int PropertyExpressionEngine::getMemSize() const { return 0; @@ -360,15 +345,6 @@ void PropertyExpressionEngine::Restore(Base::XMLReader& reader) reader.readEndElement("ExpressionEngine"); } -/** - * @brief Update graph structure with given path and expression. - * @param path Path - * @param expression Expression to query for dependencies - * @param nodes Map with nodes of graph, including dependencies of 'expression' - * @param revNodes Reverse map of the nodes, containing only the given paths, without dependencies. - * @param edges Edges in graph - */ - void PropertyExpressionEngine::buildGraphStructures( const ObjectIdentifier& path, const std::shared_ptr expression, @@ -410,12 +386,6 @@ void PropertyExpressionEngine::buildGraphStructures( } } -/** - * @brief Create a canonical object identifier of the given object \a p. - * @param p ObjectIndentifier - * @return New ObjectIdentifier - */ - ObjectIdentifier PropertyExpressionEngine::canonicalPath(const ObjectIdentifier& oid) const { DocumentObject* docObj = freecad_cast(getContainer()); @@ -446,11 +416,6 @@ ObjectIdentifier PropertyExpressionEngine::canonicalPath(const ObjectIdentifier& return oid.canonicalPath(); } -/** - * @brief Number of expressions managed by this object. - * @return Number of expressions. - */ - size_t PropertyExpressionEngine::numExpressions() const { return expressions.size(); @@ -495,12 +460,6 @@ void PropertyExpressionEngine::onContainerRestored() } } -/** - * @brief Get expression for \a path. - * @param path ObjectIndentifier to query for. - * @return Expression for \a path, or empty boost::any if not found. - */ - const boost::any PropertyExpressionEngine::getPathValue(const App::ObjectIdentifier& path) const { // Get a canonical path @@ -514,13 +473,6 @@ const boost::any PropertyExpressionEngine::getPathValue(const App::ObjectIdentif return boost::any(); } -/** - * @brief Set expression with optional comment for \a path. - * @param path Path to update - * @param expr New expression - * @param comment Optional comment. - */ - void PropertyExpressionEngine::setValue(const ObjectIdentifier& path, std::shared_ptr expr) { @@ -558,11 +510,9 @@ void PropertyExpressionEngine::setValue(const ObjectIdentifier& path, } } -/** - * @brief The cycle_detector struct is used by the boost graph routines to detect cycles in the - * graph. - */ +/* The cycle_detector struct is used by the boost graph routines to detect + * cycles in the graph. */ struct cycle_detector: public boost::dfs_visitor<> { cycle_detector(bool& has_cycle, int& src) @@ -582,14 +532,6 @@ protected: int& _src; }; -/** - * @brief Build a graph of all expressions in \a exprs. - * @param exprs Expressions to use in graph - * @param revNodes Map from int[nodeid] to ObjectIndentifer. - * @param g Graph to update. May contain additional nodes than in revNodes, because of outside - * dependencies. - */ - void PropertyExpressionEngine::buildGraph(const ExpressionMap& exprs, boost::unordered_map& revNodes, DiGraph& g, @@ -641,12 +583,6 @@ void PropertyExpressionEngine::buildGraph(const ExpressionMap& exprs, } } -/** - * The code below builds a graph for all expressions in the engine, and - * finds any circular dependencies. It also computes the internal evaluation - * order, in case properties depends on each other. - */ - std::vector PropertyExpressionEngine::computeEvaluationOrder(ExecuteOption option) { @@ -671,11 +607,6 @@ PropertyExpressionEngine::computeEvaluationOrder(ExecuteOption option) return evaluationOrder; } -/** - * @brief Compute and update values of all registered expressions. - * @return StdReturn on success. - */ - DocumentObjectExecReturn* App::PropertyExpressionEngine::execute(ExecuteOption option, bool* touched) { @@ -808,12 +739,6 @@ DocumentObjectExecReturn* App::PropertyExpressionEngine::execute(ExecuteOption o return DocumentObject::StdReturn; } -/** - * @brief Find paths to document object. - * @param obj Document object - * @param paths Object identifier - */ - void PropertyExpressionEngine::getPathsToDocumentObject( DocumentObject* obj, std::vector& paths) const @@ -839,11 +764,6 @@ void PropertyExpressionEngine::getPathsToDocumentObject( } } -/** - * @brief Determine whether any dependencies of any of the registered expressions have been touched. - * @return True if at least on dependency has been touched. - */ - bool PropertyExpressionEngine::depsAreTouched() const { for (auto& v : _Deps) { @@ -855,13 +775,6 @@ bool PropertyExpressionEngine::depsAreTouched() const return false; } -/** - * @brief Validate the given path and expression. - * @param path Object Identifier for expression. - * @param expr Expression tree. - * @return Empty string on success, error message on failure. - */ - std::string PropertyExpressionEngine::validateExpression(const ObjectIdentifier& path, std::shared_ptr expr) const @@ -913,11 +826,6 @@ PropertyExpressionEngine::validateExpression(const ObjectIdentifier& path, return {}; } -/** - * @brief Rename paths based on \a paths. - * @param paths Map with current and new object identifier. - */ - void PropertyExpressionEngine::renameExpressions( const std::map& paths) { @@ -950,11 +858,6 @@ void PropertyExpressionEngine::renameExpressions( hasSetValue(); } -/** - * @brief Rename object identifiers in the registered expressions. - * @param paths Map with current and new object identifiers. - */ - void PropertyExpressionEngine::renameObjectIdentifiers( const std::map& paths) { diff --git a/src/App/PropertyExpressionEngine.h b/src/App/PropertyExpressionEngine.h index b1d83e0a56..6b9d8b9b38 100644 --- a/src/App/PropertyExpressionEngine.h +++ b/src/App/PropertyExpressionEngine.h @@ -138,8 +138,30 @@ public: void Restore(Base::XMLReader& reader) override; + /** + * @brief Set a given expression to @a path. + * + * Note that the "value" in this context is an expression. This means that + * this function does not evaluate the expression and updates the property + * that @a path points to. It merely registers the expression to be used + * when evaluating the property later. + * + * @param[in] path The path that the expression is targeting. + * @param[in] expr The new expression. + */ void setValue(const App::ObjectIdentifier& path, std::shared_ptr expr); + /** + * @brief Get the expression for @a path. + * + * Note that the "value" in this context is an expression. This means that + * this function does not return the evaluated value of the property that + * @a path points to. It merely returns the registered expression. + * + * @param[in] path ObjectIndentifier to query for. + * + * @return The expression for @a path, or empty boost::any if not found. + */ const boost::any getPathValue(const App::ObjectIdentifier& path) const override; /// Execute options @@ -154,14 +176,39 @@ public: /// Execute on document restore ExecuteOnRestore, }; - /** Evaluate the expressions + + /** + * @brief Evaluate the expressions. * - * @param option: execution option, see ExecuteOption. + * Evaluate the expressions and update the properties they are bound to. + * + * @param[in] option: execution option, see ExecuteOption. + * @param[out] touched: if not null, set to true if any property was + * changed. + * + * @return On success a pointer to DocumentObject::StdReturn is returned. On failure, it + * returns a pointer to a newly created App::DocumentObjectExecReturn that contains the error + * message. */ DocumentObjectExecReturn* execute(ExecuteOption option = ExecuteAll, bool* touched = nullptr); - void getPathsToDocumentObject(DocumentObject*, std::vector& paths) const; + /** + * @brief Find the paths to a given document object. + * + * @param[in] obj The document object to find paths to. + * @param[out] paths Object identifiers that point to @a obj. + */ + void getPathsToDocumentObject(DocumentObject* obj, + std::vector& paths) const; + /** + * @brief Check if any dependencies are touched. + * + * Determine whether any dependencies of any of the registered expressions + * have been touched. + * + * @return True if at least on dependency has been touched. + */ bool depsAreTouched() const; /* Expression validator */ @@ -170,16 +217,41 @@ public: validator = f; } + /** + * @brief Validate the expression expression for a given path. + * + * @param[in] path The object identifier that the expression is targeting. + * @param expr The expression to validate. + * + * @return An empty string on success, an error message on failure. + */ std::string validateExpression(const App::ObjectIdentifier& path, std::shared_ptr expr) const; + /** + * @brief Rename object identifiers in the registered expressions. + * + * @param[in] paths A map with the current and new object identifiers. + */ void renameExpressions(const std::map& paths); + /** + * @brief Rename object identifiers in the registered expressions. + * + * @param[in] paths A map with the current and new object identifiers. + */ void renameObjectIdentifiers(const std::map& paths); - App::ObjectIdentifier canonicalPath(const App::ObjectIdentifier& p) const override; + /** + * @brief Create a canonical object identifier of the given object \a p. + * + * @param oid The object identifier from which we want a canonical path. + * @return The canonical object identifier. + */ + App::ObjectIdentifier canonicalPath(const App::ObjectIdentifier& oid) const override; + /// Get the number of expressions managed by this object. size_t numExpressions() const; /// signal called when an expression was changed @@ -210,14 +282,42 @@ private: using ExpressionMap = std::map; #endif + /** + * @brief Compute the evaluation order of the expressions. + * + * This method builds a graph for all expressions in the engine, and finds + * any circular dependencies. It also computes the internal evaluation + * order, in case properties depend on each other. + * + * @param[in] option Execution option, see ExecuteOption. + * + * @return A vector with the evaluation order of the properties and their + * dependencies in terms of object identifiers. + * + * @throws Base::RuntimeError if a circular dependency is detected. + */ std::vector computeEvaluationOrder(ExecuteOption option); + /** + * @brief Update graph structure with given path and expression. + * @param path Path + * @param expression Expression to query for dependencies + * @param nodes Map with nodes of graph, including dependencies of 'expression' + * @param revNodes Reverse map of the nodes, containing only the given paths, without dependencies. + * @param edges Edges in graph + */ void buildGraphStructures(const App::ObjectIdentifier& path, const std::shared_ptr expression, boost::unordered_map& nodes, boost::unordered_map& revNodes, std::vector& edges) const; - + /** + * @brief Build a graph of all expressions in \a exprs. + * @param exprs Expressions to use in graph + * @param revNodes Map from int[nodeid] to ObjectIndentifer. + * @param g Graph to update. May contain additional nodes than in revNodes, because of outside + * dependencies. + */ void buildGraph(const ExpressionMap& exprs, boost::unordered_map& revNodes, DiGraph& g,