Merge pull request #25198 from pieterhijma/doc-expressions

Doc: Improve the documentation of expressions

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> 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();
@@ -510,12 +475,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
@@ -529,13 +488,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)
 {
@@ -573,11 +525,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)
@@ -597,14 +547,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,
@@ -656,12 +598,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)
 {
@@ -686,11 +622,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)
 {
@@ -823,12 +754,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
@@ -854,11 +779,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) {
@@ -870,13 +790,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
@@ -928,11 +841,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)
 {
@@ -965,11 +873,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)
 {