Cleanup in doxygen stuff

src/Mod/AddonManager/AddonManager.py

@@ -29,13 +29,13 @@ __title__="FreeCAD Addon Manager Module"
 __author__ = "Yorik van Havre","Jonathan Wiedemann","Kurt Kremitzki"
 __url__ = "http://www.freecadweb.org"
 
-'''
+"""
 FreeCAD Addon Manager Module
 
 It will fetch its contents from https://github.com/FreeCAD/FreeCAD-addons
 You need a working internet connection, and optionally the GitPython package
 installed.
-'''
+"""
 
 import os
 import re
@@ -51,10 +51,13 @@ from addonmanager_workers import *
 def QT_TRANSLATE_NOOP(ctx,txt):
     return txt
 
+## \defgroup ADDONMANAGER AddonManager
+#  \ingroup ADDONMANAGER
+#  \brief The Addon Manager allows to install workbenches and macros made by users
+#  @{
 
 class CommandAddonManager:
-
-    "The Addon Manager command"
+    """The main Addon Manager class and FreeCAD command"""
 
     def GetResources(self):
 
@@ -79,6 +82,8 @@ class CommandAddonManager:
 
     def launch(self):
 
+        """Shows the Addon Manager UI"""
+
         import FreeCADGui
         from PySide import QtGui
         
@@ -155,7 +160,7 @@ class CommandAddonManager:
 
     def reject(self):
 
-        "called when the window has been closed"
+        """called when the window has been closed"""
 
         # save window geometry and splitter state for next use
         pref = FreeCAD.ParamGet("User parameter:BaseApp/Preferences/Addons")
@@ -200,7 +205,7 @@ class CommandAddonManager:
 
     def update(self):
 
-        "updates the list of workbenches"
+        """updates the list of workbenches"""
 
         self.dialog.listWorkbenches.clear()
         self.dialog.buttonExecute.setEnabled(False)
@@ -231,7 +236,7 @@ class CommandAddonManager:
 
     def apply_updates(self):
         
-        "apply all available updates"
+        """apply all available updates"""
         
         if self.doUpdate:
             self.install(self.doUpdate)
@@ -239,7 +244,7 @@ class CommandAddonManager:
 
     def enable_updates(self,num):
         
-        "enables the update button"
+        """enables the update button"""
         
         if num:
             self.dialog.buttonUpdateAll.setText(translate("AddonsInstaller","Apply")+" "+str(num)+" "+translate("AddonsInstaller","update(s)"))
@@ -250,7 +255,7 @@ class CommandAddonManager:
 
     def add_addon_repo(self, addon_repo):
 
-        "adds a workbench to the list"
+        """adds a workbench to the list"""
 
         from PySide import QtGui
         self.repos.append(addon_repo)
@@ -267,7 +272,7 @@ class CommandAddonManager:
 
     def show_information(self, label):
 
-        "shows text in the information pane"
+        """shows text in the information pane"""
 
         self.dialog.description.setText(label)
         if self.dialog.listWorkbenches.isVisible():
@@ -277,7 +282,7 @@ class CommandAddonManager:
 
     def show(self,idx):
 
-        "loads information of a given workbench"
+        """loads information of a given workbench"""
 
         # this function is triggered also when the list is populated, prevent that here
         if idx == 0 and self.firsttime:
@@ -300,7 +305,7 @@ class CommandAddonManager:
 
     def show_macro(self,idx):
 
-        "loads information of a given macro"
+        """loads information of a given macro"""
 
         # this function is triggered when the list is populated, prevent that here
         if idx == 0 and self.firstmacro:
@@ -328,7 +333,7 @@ class CommandAddonManager:
 
     def switchtab(self,idx):
 
-        "does what needs to be done when switching tabs"
+        """does what needs to be done when switching tabs"""
 
         if idx == 1:
             if not self.macros:
@@ -343,13 +348,13 @@ class CommandAddonManager:
 
     def update_repos(self, repos):
 
-        "convenience function to update the internal list of workbenches"
+        """convenience function to update the internal list of workbenches"""
 
         self.repos = repos
 
     def add_macro(self, macro):
 
-        "adds a macro to the list"
+        """adds a macro to the list"""
 
         if macro.name:
             if macro in self.macros:
@@ -372,7 +377,7 @@ class CommandAddonManager:
 
     def install(self,repos=None):
 
-        "installs a workbench or macro"
+        """installs a workbench or macro"""
 
         if self.dialog.tabWidget.currentIndex() == 0:
             # Tab "Workbenches".
@@ -405,7 +410,7 @@ class CommandAddonManager:
 
     def show_progress_bar(self, state):
 
-        "shows or hides the progress bar"
+        """shows or hides the progress bar"""
 
         if state == True:
             self.dialog.tabWidget.setEnabled(False)
@@ -425,7 +430,7 @@ class CommandAddonManager:
 
     def executemacro(self):
 
-        "executes a selected macro"
+        """executes a selected macro"""
 
         import FreeCADGui
         if self.dialog.tabWidget.currentIndex() == 1:
@@ -446,14 +451,14 @@ class CommandAddonManager:
 
     def remove_readonly(self, func, path, _):
 
-        "Remove a read-only file."
+        """Remove a read-only file."""
 
         os.chmod(path, stat.S_IWRITE)
         func(path)
 
     def remove(self):
 
-        "uninstalls a macro or workbench"
+        """uninstalls a macro or workbench"""
 
         if self.dialog.tabWidget.currentIndex() == 0:
             # Tab "Workbenches".
@@ -479,7 +484,7 @@ class CommandAddonManager:
 
     def mark_recompute(self,addon):
 
-        "marks an addon in the list as installed but needs recompute"
+        """marks an addon in the list as installed but needs recompute"""
 
         for i in range(self.dialog.listWorkbenches.count()):
             txt = self.dialog.listWorkbenches.item(i).text().strip()
@@ -494,8 +499,8 @@ class CommandAddonManager:
 
     def update_status(self,soft=False):
 
-        """Updates the list of workbenches/macros.
-           If soft is true, items are not recreated (and therefore display text isn't triggered)"
+        """Updates the list of workbenches/macros. If soft is true, items 
+        are not recreated (and therefore display text isn't triggered)"
         """
 
         moddir = FreeCAD.getUserAppDataDir() + os.sep + "Mod"
@@ -547,7 +552,7 @@ class CommandAddonManager:
 
     def mark(self,repo):
 
-        "mark a workbench as updatable"
+        """mark a workbench as updatable"""
 
         from PySide import QtGui
         for i in range(self.dialog.listWorkbenches.count()):
@@ -560,7 +565,7 @@ class CommandAddonManager:
 
     def show_config(self):
 
-        "shows the configuration dialog"
+        """shows the configuration dialog"""
 
         import FreeCADGui
         from PySide import QtGui
@@ -580,3 +585,5 @@ class CommandAddonManager:
             # OK button has been pressed
             pref.SetBool("AutoCheck",self.config.checkUpdates.isChecked())
             pref.SetString("CustomRepositories",self.config.customRepositories.toPlainText())
+
+## @}

src/Mod/AddonManager/addonmanager.dox

@@ -0,0 +1,4 @@
+/** \defgroup ADDONMANAGER Addon Manager
+ *  \ingroup PYTHONWORKBENCHES 
+ *  \brief Application that handles the installation of user-made workbenches and macros
+ */

src/Mod/AddonManager/addonmanager_macro.py

@@ -21,6 +21,10 @@
 #*                                                                         *
 #***************************************************************************
 
+## @package AddonManager_macro
+#  \ingroup ADDONMANAGER
+#  \brief Unified handler for FreeCAD macros that can be obtained from different sources
+
 import os
 import re
 import sys
@@ -31,6 +35,8 @@ from addonmanager_utilities import urlopen
 
 
 class Macro(object):
+    """This class provides a unified way to handle macros coming from different sources"""
+
     def __init__(self, name):
         self.name = name
         self.on_wiki = False

src/Mod/AddonManager/addonmanager_utilities.py

@@ -27,6 +27,10 @@ import FreeCAD
 import shutil
 import re
 
+## @package AddonManager_utilities
+#  \ingroup ADDONMANAGER
+#  \brief Utilities to work across different platforms, providers and python versions
+
 # check for SSL support
 
 ssl_ctx = None

src/Mod/AddonManager/addonmanager_workers.py

@@ -35,19 +35,22 @@ import addonmanager_utilities as utils
 from addonmanager_utilities import translate # this needs to be as is for pylupdate
 from addonmanager_macro import Macro
 
+## @package AddonManager_workers
+#  \ingroup ADDONMANAGER
+#  \brief Multithread workers for the addon manager
+
 MACROS_BLACKLIST = ["BOLTS","WorkFeatures","how to install","PartsLibrary","FCGear"]
 OBSOLETE = ["assembly2","drawing_dimensioning","cura_engine"] # These addons will print an additional message informing the user
 NOGIT = False # for debugging purposes, set this to True to always use http downloads
 
 
 
-"Multithread workers for the Addon Manager"
+"""Multithread workers for the Addon Manager"""
 
 
 
 class UpdateWorker(QtCore.QThread):
-
-    "This worker updates the list of available workbenches"
+    """This worker updates the list of available workbenches"""
 
     info_label = QtCore.Signal(str)
     addon_repo = QtCore.Signal(object)
@@ -119,8 +122,7 @@ class UpdateWorker(QtCore.QThread):
 
 
 class InfoWorker(QtCore.QThread):
-
-    "This worker retrieves the description text of a workbench"
+    """This worker retrieves the description text of a workbench"""
 
     addon_repos = QtCore.Signal(object)
 
@@ -153,8 +155,7 @@ class InfoWorker(QtCore.QThread):
 
 
 class CheckWBWorker(QtCore.QThread):
-
-    "This worker checks for available updates for all workbenches"
+    """This worker checks for available updates for all workbenches"""
 
     enable = QtCore.Signal(int)
     mark = QtCore.Signal(str)
@@ -212,8 +213,7 @@ class CheckWBWorker(QtCore.QThread):
 
 
 class FillMacroListWorker(QtCore.QThread):
-
-    "This worker opulates the list of macros"
+    """This worker opulates the list of macros"""
 
     add_macro_signal = QtCore.Signal(Macro)
     info_label_signal = QtCore.Signal(str)
@@ -293,8 +293,7 @@ class FillMacroListWorker(QtCore.QThread):
 
 
 class ShowWorker(QtCore.QThread):
-
-    "This worker retrieves info of a given workbench"
+    """This worker retrieves info of a given workbench"""
 
     info_label = QtCore.Signal(str)
     addon_repos = QtCore.Signal(object)

src/Mod/Arch/Dice3DS/dice3ds.dox

@@ -0,0 +1,5 @@
+/**
+   \defgroup DICE3DS Dice 3DS
+   \ingroup EMBEDDED
+   \brief The Dice 3DS library provides 3DStudio files import to the Arch module
+ */

src/Mod/Arch/OfflineRenderingUtils.py

@@ -22,8 +22,16 @@
 #*                                                                         *
 #***************************************************************************
 
+## \defgroup OFFLINERENDERINGUTILS OfflineRenderingUtils
+#  \ingroup UTILITIES
+#  \brief Utility functions to work with FreeCAD files in console mode
+#
+# Offline rendering utilities
 
-"""
+## \addtogroup OFFLINERENDERINGUTILS
+#  @{
+
+"""@package docstring
 OfflineRenderingUtils - Utilities to help producing files with colors from FreeCAD in non-GUI mode
 
 
@@ -96,7 +104,6 @@ OfflineRenderingUtils.viewer(scene)
 OfflineRenderingUtils.save(doc,filename=baseFileName+"_exported.FCStd",colors=colors,camera=camera)
 """
 
-
 import sys
 import os
 import xml.sax
@@ -749,3 +756,5 @@ def extract(filename,inputpath,outputpath=None):
                     of.close()
                 else:
                     return data
+
+##  @}

src/Mod/Draft/DraftGeomUtils.py

@@ -26,7 +26,7 @@ __author__ = "Yorik van Havre, Jacques-Antoine Gaudin, Ken Cline"
 __url__ = ["http://www.freecadweb.org"]
 
 ## \defgroup DRAFTGEOMUTILS DraftGeomUtils
-#  \ingroup DRAFT
+#  \ingroup UTILITIES
 #  \brief Shape manipulation utilities for the Draft workbench
 #
 # Shapes manipulation utilities

src/Mod/Draft/DraftVecUtils.py

@@ -28,7 +28,7 @@ __url__ = ["http://www.freecadweb.org"]
 "a vector math library for FreeCAD"
 
 ## \defgroup DRAFTVECUTILS DraftVecUtils
-#  \ingroup DRAFT
+#  \ingroup UTILITIES
 #  \brief Vector math utilities used in Draft workbench
 #
 # Vector math utilities

src/Mod/Fem/fem.dox

@@ -1,5 +1,5 @@
 /** \defgroup FEM Fem
- *  \ingroup CWORKBENCHES 
+ *  \ingroup PYTHONWORKBENCHES 
  *  \brief Finite Elements Analysis workbench
  */
 

src/Mod/Mesh/App/WildMagic4/wildmagic4.dox

@@ -1,6 +1,6 @@
 
 /** \defgroup WM4 WildMagic4
- *  \ingroup MESH
+ *  \ingroup EMBEDDED
  *  Excerpts from version 4.0.0 of Wild Magic Library which were integrated
  *  to FreeCAD's Mesh module.
  *  

src/Mod/Path/App/ParamsHelper.h

@@ -24,6 +24,7 @@
 #define PARAMS_HELPER_H
 
 /** \page ParamPage Parameter helper macros
+ * \ingroup PATH
  * Collections of macros for managing groups of parameters.
  *
  * \section Motivation 
@@ -178,6 +179,7 @@
 #include <boost/preprocessor/comparison/greater.hpp>
 
 /** \defgroup ParamHelper Parameters helper macros
+ * \ingroup PATH
  * Collections of macros for managing groups of parameters */
 
 /**

src/Mod/Path/path.dox

@@ -1,4 +1,4 @@
 /** \defgroup PATH Path
- *  \ingroup CWORKBENCHES 
+ *  \ingroup PYTHONWORKBENCHES 
  *  \brief Tools to generate CNC toolpaths and G-Code
  */

src/Mod/mod.dox

@@ -1,5 +1,5 @@
 /** \addtogroup WORKBENCHES
-    Additional functionality and GUI tools
+    Most of FreeCAD's functionality is defined in dedicated Workbenches
 
     Those plugins, also called \b modules or \b worbenches, provide
     functionality for specialized facets of FreeCAD. The word \b module
@@ -12,18 +12,16 @@
     Some of these modules are programmed in C++, others in Python, and some
     in a mix of C++ and Python.
 
-    \b Warning: Some are really work-in-progress and are not yet included in
-    the official builds
  */
  
- /** \defgroup PYTHONWORKBENCHES Python workbenches
- * \ingroup WORKBENCHES
- * \brief Those are workbenches programmed fully in Python
-*/
-
  /** \defgroup CWORKBENCHES C++ workbenches
  * \ingroup WORKBENCHES
- * \brief Those are workbenches programmed primarily in C++. They usually provide a Python API as well.
+ * \brief These workbenches are programmed primarily in C++, but most provide a Python API as well.
+*/
+
+ /** \defgroup PYTHONWORKBENCHES Python workbenches
+ * \ingroup WORKBENCHES
+ * \brief Those are workbenches programmed primarily in Python
 */
 
  /** \defgroup UTILITIES Utility modules