kindred/create
1
1
Fork 0
Code Issues 53 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

Doc: Move doc comments in PropertyExpressionEngine

Browse Source 
Several doc comments in App/PropertyExpressionEngine.cpp are moved to
header files.
This commit is contained in:
Pieter Hijma
2025-10-28 15:45:40 +01:00
committed by Chris Hennes
parent f113e775a1
commit ee538f707f
2 changed files with 108 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
src/App/PropertyExpressionEngine.cpp
View File

@@ -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> 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<DocumentObject*>(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<Expression> 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<int, ObjectIdentifier>& 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<App::ObjectIdentifier>
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<App::ObjectIdentifier>& 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<const Expression> 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<ObjectIdentifier, ObjectIdentifier>& 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<ObjectIdentifier, ObjectIdentifier>& paths)
{

110
src/App/PropertyExpressionEngine.h
View File

@@ -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<App::Expression> 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<App::ObjectIdentifier>& 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<App::ObjectIdentifier>& 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<const App::Expression> 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<App::ObjectIdentifier, App::ObjectIdentifier>& 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<App::ObjectIdentifier, App::ObjectIdentifier>& 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<const App::ObjectIdentifier, ExpressionInfo>;
#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<App::ObjectIdentifier> 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> expression,
boost::unordered_map<App::ObjectIdentifier, int>& nodes,
boost::unordered_map<int, App::ObjectIdentifier>& revNodes,
std::vector<Edge>& 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<int, App::ObjectIdentifier>& revNodes,
DiGraph& g,