Merge pull request #594 from emsec/doc/update_doc

updated code documentation and changelog

CHANGELOG.md

@@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased] 
 * added `dataflow::Result::create_modules` function that takes nothing but group IDs for easier module creation
+* changed and unified context menus for all widgets related to netlist elements
+* fixed module colors not updating on creation of modules with previously used ids
+* added python bindings `gui.View` for management of contexts and directories
 
 ## [4.4.1](v4.4.1) - 2024-07-29 14:21:42+02:00 (urgency: medium)
 * fixed `hal_py.GateLibrary.gate_types` pybind

plugins/gui/include/gui/context_manager_widget/models/context_tree_model.h

@@ -112,8 +112,22 @@ namespace hal
         QVariant data(const QModelIndex& inddex, int role = Qt::DisplayRole) const override;
         ///@}
 
+        /**
+         * Returns the ContextTreeItem of a directory specified by an id.
+         * 
+         * @param directoryId - The id of the directory whose ContextTreeItem should be returned.
+         * 
+         * @return The ContextTreeItem for the directory specified by the id.
+         */
         BaseTreeItem* getDirectory(u32 directoryId) const;
 
+        /**
+         * Returns the ContextTreeItem of a context specified by an id.
+         * 
+         * @param contextId - The id of the context whose ContextTreeItem should be returned.
+         * 
+         * @return The ContextTreeItem for the context specified by the id.
+         */
         BaseTreeItem* getContext(u32 contextId) const;
 
         /**

plugins/gui/include/gui/grouping/grouping_manager_widget.h

@@ -196,8 +196,22 @@ namespace hal
          */
         void newGroupingByDistance(int maxDepth, bool succ, const GraphicsItem* item);
 
+        /**
+         * Opens a GroupingDialog where the user can select a grouping to add/move the specified netlist elements to.
+         * 
+         * @param modules - QSet of ids of modules to be moved to a grouping.
+         * @param gates - QSet of ids of gates to be moved to a grouping.
+         * @param nets - QSet of ids of nets to be moved to a grouping.
+         */
         void assignElementsToGroupingDialog(const QSet<u32>& modules = QSet<u32>(), const QSet<u32>& gates = QSet<u32>(), const QSet<u32>& nets = QSet<u32>());
 
+        /**
+         * Removes the specified netlist elements from their grouping.
+         * 
+         * @param modules - QSet of ids of modules to be removed from their groupings.
+         * @param gates - QSet of ids of gates to be removed from their groupings.
+         * @param nets - QSet of ids of nets to be removed from their groupings.
+         */
         void removeElementsFromGrouping(const QSet<u32>& modules = QSet<u32>(), const QSet<u32>& gates = QSet<u32>(), const QSet<u32>& nets = QSet<u32>());
 
     public Q_SLOTS:
@@ -314,6 +328,13 @@ namespace hal
          */
         void handleDoubleClicked(const QModelIndex& index);
 
+        /**
+         * Q_SLOT to handle focusChanged signal. Enables or disabled the delete shortcut depending on
+         * if this widget is in focus.
+         *
+         * @param oldWidget - The last selected widget. Is ignored.
+         * @param newWidget - The newly selected widget.
+         */
         void handleDeleteShortcutOnFocusChanged(QWidget *oldWidget, QWidget *newWidget);
 
     private:

plugins/gui/include/gui/gui_api/gui_api.h

@@ -43,17 +43,113 @@ namespace hal
 
         class View{
         public:
-            static int isolateInNew(const std::vector<Module*>, const std::vector<Gate*>);
+            /**
+             * Isolates given modules and gates into a new view.
+             * If only one module and no gates are given and 
+             * there already exists a view which is exclusively bound the given module, 
+             * then that view is returned instead.
+             * 
+             * @param modules - List of modules to be added.
+             * @param gates - List of gates to be added
+             * 
+             * @return The id of the requested view. Returns 0 if the view could not be created.
+             */
+            static int isolateInNew(const std::vector<Module*> modules, const std::vector<Gate*> gates);
+            /**
+             * Deletes a view.
+             * 
+             * @param id - The id of the view.
+             * 
+             * @return True on success, otherwise false.
+             */
             static bool deleteView(int id);
-            static bool addTo(int id, const std::vector<Module*>, const std::vector<Gate*>);
-            static bool removeFrom(int id, const std::vector<Module*>, const std::vector<Gate*>);
+            /**
+             * Adds modules and gates to a view.
+             * 
+             * @param id - The id of the view.
+             * @param modules - The list of modules to be added to the view.
+             * @param gates - The list of gates to be added to the view.
+             * 
+             * @return True on success, otherwise false.
+             */
+            static bool addTo(int id, const std::vector<Module*> modules, const std::vector<Gate*> gates);
+            /**
+             * Removes modules and gates from a view.
+             * 
+             * @param id - The id of the view to remove the modules and gates from.
+             * @param modules - The modules to be removed from the view.
+             * @param gates - The gates to be removed from the view.
+             * 
+             * @return True on success, otherwise false.
+             */
+            static bool removeFrom(int id, const std::vector<Module*> modules, const std::vector<Gate*> gates);
+            /**
+             * Sets the name of a view.
+             * 
+             * @param id - The id of the view.
+             * @param name - The new name of the view.
+             * 
+             * @return True on success, otherwise false.
+             */
             static bool setName(int id, const std::string& name);
+            /**
+             * Returns the id of a view.
+             * 
+             * @param name - The name of the view to search for.
+             * 
+             * @return The id of the view. Returns 0, if the view was not found.
+             */
             static int getId(const std::string& name);
+            /**
+             * Returns the name of a view.
+             * 
+             * @param id - The id of the view.
+             * 
+             * @return The name of the view. Returns an empty string, if the view was not found.
+             */
             static std::string getName(int id);
+            /**
+             * Returns the modules contained in a view.
+             * 
+             * @param id - The id of the view.
+             * 
+             * @return A list of modules. Returns an empty list, if the view was not found.
+             */
             static std::vector<Module*> getModules(int id);
+            /**
+             * Returns the gates contained in a view.
+             * 
+             * @param id - The id of the view.
+             * 
+             * @return A list of gates. Returns an empty list, if the view was not found.
+             */
             static std::vector<Gate*> getGates(int id);
+            /**
+             * Returns the ids of views containing at least the given modules and gates.
+             * 
+             * @param modules - List of required modules.
+             * @param gates - List of required gates.
+             * 
+             * @return A list of ids of views, which contain all given modules and gates.
+             */
             static std::vector<u32> getIds(const std::vector<Module*> modules, const std::vector<Gate*> gates);
+            /**
+             * Fold a specific module. Hides the submodules and gates, shows the specific module.
+             * 
+             * @param view_id - The id of the view.
+             * @param module - The Module to fold.
+             *
+             * @return True on success, otherwise False.
+             */
             static bool foldModule(int view_id, Module* module);
+            /**
+             * Unfold a specific module. Hides the module, shows submodules and gates.
+             * 
+             * @param view_id - The id of the view.
+             * @param module - The Module to unfold.
+             *
+             * @return True on success, otherwise False.
+             */
             static bool unfoldModule(int view_id, Module* module);
 
             struct ModuleGateIdPair {
@@ -65,14 +161,72 @@ namespace hal
             static GridPlacement* getGridPlacement(int viewId);
             static bool setGridPlacement(int viewId, GridPlacement* gp);
 
+            /**
+             * Returns the id of the current directory.
+             * 
+             * Used for selection and similar.
+             * 
+             * @returns The id of the current directory.
+             */
             static u32 getCurrentDirectory();
+            /**
+             * Sets the id of the current directory.
+             * 
+             * Used for selection and similar.
+             * 
+             * @param id - The id of the new current directory.
+             */
             static void setCurrentDirectory(u32 id);
+            /**
+             * Creates a new directory with a given name.
+             * 
+             * @param name - The name of the new directory.
+             * 
+             * @return The id of the newly created directory.
+             */
             static u32 createNewDirectory(const std::string& name);
+            /**
+             * Deleted a directory.
+             * 
+             * @param id - The id of the directory.
+             */
             static void deleteDirectory(u32 id);
+            /**
+             * Moves a view to a directory.
+             * 
+             * @param viewId - The id of the view.
+             * @param destinationDirectoryId - The id of the destination directory. 
+             *                                 If not given, the current directory is used instead.
+             * @param row - Optional. The row there the view is inserted.
+             */
             static void moveView(u32 viewId, std::optional<u32> destinationDirectoryId, std::optional<int> row);
+            /**
+             * Moves a directory under another directory.
+             * 
+             * @param directoryId - The id of the directory to move.
+             * @param destinationDirectoryId - The id of the destination directory.
+             *                                 If not given, the current directory is used instead.
+             * @param row - Optional. The row there the view is inserted.
+             */
             static void moveDirectory(u32 directoryId, std::optional<u32> destinationDirectoryId, std::optional<int> row);
 
+            /**
+             * Returns a list of child directories for a given directory.
+             * 
+             * @param directoryId - The id of the parent directory.
+             * 
+             * @return List of ids of child directories. 
+             *         If the parent directory does not exist std::nullopt is returned instead.
+             */
             static std::optional<std::vector<u32>> getChildDirectories(u32 directoryId);
+            /**
+             * Returns a list of child views for a given directory.
+             * 
+             * @param directoryId - The id of the parent directory.
+             * 
+             * @return List of ids of child views. 
+             *         If the parent directory does not exist std::nullopt is returned instead.
+             */
             static std::optional<std::vector<u32>> getChildViews(u32 directoryId);
         };
     }

plugins/gui/include/gui/module_context_menu/module_context_menu.h

@@ -9,9 +9,35 @@ namespace hal {
     class ModuleContextMenu
     {
         public:
+            /**
+             * Adds general context menu actions for a specified module.
+             * 
+             * @param contextMenu - The QMenu to which the actions are added to.
+             * @param id - The id of the module on which the actions will operate.
+             */
             static void addModuleSubmenu(QMenu* contextMenu, u32 id);
+            /**
+             * Adds general context menu actions for a specified gate.
+             * 
+             * @param contextMenu - The QMenu to which the actions are added to.
+             * @param id - The id of the gate on which the actions will operate.
+             */
             static void addGateSubmenu(QMenu* contextMenu, u32 id);
+            /**
+             * Adds general context menu actions for a specified net.
+             * 
+             * @param contextMenu - The QMenu to which the actions are added to.
+             * @param id - The id of the net on which the actions will operate.
+             */
             static void addNetSubmenu(QMenu* contextMenu, u32 id);
+            /**
+             * Adds general context menu actions for multiple specified netlist elements.
+             * 
+             * @param contextMenu - The QMenu to which the actions are added to.
+             * @param modules - QSet with ids of modules on which the actions will operate.
+             * @param gates - QSet with ids of gates on which the actions will operate.
+             * @param nets - QSet with ids of nets on which the actions will operate.
+             */
             static void addMultipleElementsSubmenu(QMenu* contextMenu, const QSet<u32>& modules = QSet<u32>(), const QSet<u32>& gates = QSet<u32>(), const QSet<u32>& nets = QSet<u32>());
     };
 }

plugins/gui/include/gui/module_model/module_item.h

@@ -52,16 +52,38 @@ namespace hal
          */
         enum class TreeItemType {Module, Gate, Net};
 
+        /**
+         * Sets the data for the columns name and type. 
+         * Column 2 (type) can be only set, if this item is a module.
+         *
+         * @param data - Each entry in the list represents one column. 
+         *               The second column (id) is ignored.
+         */
         void setData(QList<QVariant> data) override;
+        /**
+         * Sets the data for a specified column. Column 2 (type) can only be set, if this item is a module.
+         *
+         * @param index - The column to set the new data. Either 0 (name) or 2(type). Other columns will be ignored.
+         * @param data - The new column data.
+         */
         void setDataAtIndex(int index, QVariant& data) override;
+        /**
+         * Unused dummy function overwritten from parent class.
+         */
         void appendData(QVariant data) override;
+        /**
+         * Get the number of currently stored column data.
+         *
+         * @return 3
+         */
         int getColumnCount() const override;
 
         /**
          * Constructor.
          *
          * @param id - The id of the netlist item this ModuleItem represents
          * @param type - The type of the netlist item
+         * @param model - The parent model where this item is added to.
          */
         ModuleItem(const u32 id, const TreeItemType type, ModuleModel* model);
 

plugins/gui/include/gui/plugin_relay/gui_plugin_manager.h

@@ -202,6 +202,16 @@ namespace hal {
     public:
         GuiPluginManager(QWidget* parent = nullptr);
         static QMap<QString,GuiExtensionInterface*> getGuiExtensions();
+        /**
+         * Adds context menu actions, which are provided by currently loaded plugins, 
+         * for specified set of netlist elements to a QMenu.
+         * 
+         * @param contextMenu - The QMenu to which the actions are added to.
+         * @param netlist - The netlist associated with the netlist elements.
+         * @param modules - List with ids of modules on which the actions will operate.
+         * @param gates - List with ids of gates on which the actions will operate.
+         * @param nets - List with ids of nets on which the actions will operate.
+         */
         static void addPluginSubmenus(QMenu* contextMenu, Netlist* netlist,
                                       const std::vector<u32>& modules,
                                       const std::vector<u32>& gates,

plugins/gui/include/gui/selection_details_widget/selection_details_icon_provider.h

@@ -56,8 +56,30 @@ namespace hal
         static bool sSettingsInitialized;
         static bool initSettings();
     public:
+        /**
+         * Returns an icon for the given styled netlist element.
+         * If the element is a module, a module icon is returned, 
+         * colored after the modules color.
+         * If the item is a gate, the gate icon corresponding to 
+         * the gates type is returned.
+         * 
+         * @param catg - The type of the netlist element, i.e. Module or Gate.
+         * @param itemId - The id of the netlist element.
+         * 
+         * @return The icon for the specified netlist element.
+         */
         const QIcon *getIcon(IconCategory catg, u32 itemId);
+
+        /**
+         * Get the singleton instance of the SettingsManager.
+         *
+         * @return The singleton instance.
+         */
         static SelectionDetailsIconProvider* instance();
+
+        /**
+         * The current icon setting. Changed by user in the settings.
+         */
         static SettingsItemDropdown* sIconSizeSetting;
     };
 }