From ec4ea7f8d3539c7938701b4f9519b5f24d62c57f Mon Sep 17 00:00:00 2001 From: Pieter Hijma Date: Mon, 24 Mar 2025 21:02:05 +0100 Subject: [PATCH] [Doc] Improve topics within App - The location of the documentation is improved (not in the cpp file anymore but in core-app.dox). This prevents cluttering source with high-level overviews typical of topic documentation. - The formatting has been made consistent. --- src/App/Document.cpp | 35 ---------- src/App/DocumentObject.cpp | 4 -- src/App/Expression.cpp | 5 -- src/App/PropertyContainer.cpp | 47 ------------- src/App/core-app.dox | 122 +++++++++++++++++++++++++++++++--- src/Doc/primary-groups.dox | 14 ++-- 6 files changed, 118 insertions(+), 109 deletions(-) diff --git a/src/App/Document.cpp b/src/App/Document.cpp index 3b7e3c2ea7..5b22ef1b8a 100644 --- a/src/App/Document.cpp +++ b/src/App/Document.cpp @@ -20,41 +20,6 @@ * * ***************************************************************************/ - -/*! -\defgroup Document Document -\ingroup APP -\brief The Base class of the FreeCAD Document - -This (besides the App::Application class) is the most important class in FreeCAD. -It contains all the data of the opened, saved, or newly created FreeCAD Document. -The App::Document manages the Undo and Redo mechanism and the linking of documents. - -\namespace App \class App::Document -This is besides the Application class the most important class in FreeCAD -It contains all the data of the opened, saved or newly created FreeCAD Document. -The Document manage the Undo and Redo mechanism and the linking of documents. - -Note: the documents are not free objects. They are completely handled by the -App::Application. Only the Application can Open or destroy a document. - -\section Exception Exception handling -As the document is the main data structure of FreeCAD we have to take a close -look at how Exceptions affect the integrity of the App::Document. - -\section UndoRedo Undo Redo an Transactions -Undo Redo handling is one of the major mechanism of a document in terms of -user friendliness and speed (no one will wait for Undo too long). - -\section Dependency Graph and dependency handling -The FreeCAD document handles the dependencies of its DocumentObjects with -an adjacence list. This gives the opportunity to calculate the shortest -recompute path. Also, it enables more complicated dependencies beyond trees. - -@see App::Application -@see App::DocumentObject -*/ - #include "PreCompiled.h" #ifndef _PreComp_ diff --git a/src/App/DocumentObject.cpp b/src/App/DocumentObject.cpp index bc5d291e7b..df544afd0b 100644 --- a/src/App/DocumentObject.cpp +++ b/src/App/DocumentObject.cpp @@ -55,10 +55,6 @@ FC_LOG_LEVEL_INIT("App", true, true) using namespace App; -/** \defgroup DocObject Document Object - \ingroup APP - \brief Base class of all objects handled in the Document -*/ PROPERTY_SOURCE(App::DocumentObject, App::TransactionalObject) diff --git a/src/App/Expression.cpp b/src/App/Expression.cpp index 115db3dd9b..9f16fdbf3a 100644 --- a/src/App/Expression.cpp +++ b/src/App/Expression.cpp @@ -52,11 +52,6 @@ #include "ExpressionParser.h" -/** \defgroup Expression Expressions framework - \ingroup APP - \brief The expression system allows users to write expressions and formulas that produce values -*/ - using namespace Base; using namespace App; diff --git a/src/App/PropertyContainer.cpp b/src/App/PropertyContainer.cpp index cbaac141f1..1b083e8552 100644 --- a/src/App/PropertyContainer.cpp +++ b/src/App/PropertyContainer.cpp @@ -640,50 +640,3 @@ void PropertyData::visitProperties(OffsetBase offsetBase, }; } -/** \defgroup PropFrame Property framework - \ingroup APP - \brief System to access object properties -\section propframe_intro Introduction -The property framework introduces the ability to access attributes (member variables) of a class by name without -knowing the class type. It's like the reflection mechanism of Java or C#. -This ability is introduced by the App::PropertyContainer class and can be used by all derived classes. - -This makes it possible in the first place to make an automatic mapping to python (e.g. in App::FeaturePy) and -abstract editing properties in Gui::PropertyEditor. - -\section Examples - -Here some little examples how to use it: - -\code -// search in PropertyList -Property *prop = _pcFeature->getPropertyByName(attr); -if(prop) -{ - return prop->getPyObject(); -} -\endcode - -or: - -\code -void PropertyContainer::Restore(Base::Reader &reader) -{ - reader.readElement("Properties"); - int Cnt = reader.getAttributeAsInteger("Count"); - - for(int i=0 ;iRestore(reader); - - reader.readEndElement("Property"); - } - reader.readEndElement("Properties"); -} -\endcode - -*/ diff --git a/src/App/core-app.dox b/src/App/core-app.dox index 1a5f38b0e9..a4fc82c12e 100644 --- a/src/App/core-app.dox +++ b/src/App/core-app.dox @@ -1,15 +1,115 @@ -/** \defgroup APP App - * \ingroup CORE - * \brief The part of FreeCAD that works without GUI (console or server mode) -*/ +/** + * @defgroup APP App + * @ingroup CORE + * @brief The part of FreeCAD that works without GUI (console or server mode) + * @details It contains the App namespace and defines core concepts such as + * @ref DocumentGroup "Document", @ref DocObject "Document Object", the @ref + * Expression "Expression Framework", and the @ref PropFrame + * "Property Framework". + */ -/** \namespace App - \ingroup APP - \brief The FreeCAD Application layer +/** + * @defgroup DocumentGroup Document + * @ingroup APP + * @brief The class that represents a FreeCAD document + * + * This (besides the App::Application class) is the most important class in FreeCAD. + * It contains all the data of the opened, saved, or newly created FreeCAD Document. + * The App::Document manages the Undo and Redo mechanism and the linking of documents. + * + * Note: the documents are not free objects. They are completely handled by the + * App::Application. Only the Application can Open or destroy a document. + * + * \section Exception Exception handling + * As the document is the main data structure of FreeCAD we have to take a close + * look at how Exceptions affect the integrity of the App::Document. + * + * \section UndoRedo Undo Redo an Transactions + * Undo Redo handling is one of the major mechanism of a document in terms of + * user friendliness and speed (no one will wait for Undo too long). + * + * \section Dependency Graph and dependency handling + * The FreeCAD document handles the dependencies of its DocumentObjects with + * an adjacency list. This gives the opportunity to calculate the shortest + * recompute path. Also, it enables more complicated dependencies beyond trees. + * + * @see App::Application + * @see App::DocumentObject + */ - This namespace includes Application services of FreeCAD like: - - The Application class - - The Document class +/** + * @defgroup DocObject Document Object + * @ingroup APP + * @brief %Base class of all objects handled in the Document. + */ + +/** + * @defgroup Expression Expressions framework + * @ingroup APP + * @brief The expression system allows users to write expressions and formulas that produce values + */ + +/** + * @defgroup PropFrame Property framework + * @ingroup APP + * @brief System to access object properties. + * + * @section propframe_intro Introduction + * + * The property framework introduces the ability to access attributes (member + * variables) of a class by name without knowing the class type. It's like the + * reflection mechanism of Java or C#. This ability is introduced by the + * App::PropertyContainer class and can be used by all derived classes. + * + * This makes it possible in the first place to make an automatic mapping to python (e.g. in App::FeaturePy) and + * abstract editing properties in Gui::PropertyEditor. + * + * @section Examples + * + * Here some little examples how to use it: + * + * @code + * // search in PropertyList + * Property *prop = _pcFeature->getPropertyByName(attr); + * if(prop) + * { + * return prop->getPyObject(); + * } + * @endcode + * + * or: + * + * @code + * void PropertyContainer::Restore(Base::Reader &reader) + * { + * reader.readElement("Properties"); + * int Cnt = reader.getAttributeAsInteger("Count"); + * + * for(int i=0 ;iRestore(reader); + * + * reader.readEndElement("Property"); + * } + * reader.readEndElement("Properties"); + * } + * @endcode + */ -*/ +/** + * @namespace App + * @ingroup APP + * @brief The namespace for the part of FreeCAD that works without GUI. + * @details This namespace includes %Application services of FreeCAD that such as: + * - The Application class + * - The Document class + * - The DocumentObject classes + * - The Expression classes + * - The Property classes + */ + diff --git a/src/Doc/primary-groups.dox b/src/Doc/primary-groups.dox index 7ec6329e65..d54bdc7504 100644 --- a/src/Doc/primary-groups.dox +++ b/src/Doc/primary-groups.dox @@ -1,15 +1,15 @@ -/** \defgroup CORE Core - These are the core components of FreeCAD. +/** @defgroup CORE Core + The core components of FreeCAD. - It groups the Base classes, and the main components of FreeCAD core, - spread over their App and Gui sides. Core components are programmed in - C++ but provide a broad Python API too. Most of FreeCAD functionality, + FreeCAD's core consists of Base classes, and the main components of FreeCAD + core, spread over their App and Gui sides. Core components are programmed + in C++ but provide a broad Python API too. Most of FreeCAD functionality, however, is defined in Workbenches. */ -/** \defgroup WORKBENCHES Workbenches +/** @defgroup WORKBENCHES Workbenches */ -/** \defgroup EMBEDDED Embedded 3rd party libraries +/** @defgroup EMBEDDED Embedded 3rd party libraries Important tools and libraries incorporated to FreeCAD. */