Improve doxygen documentation

command-line.c

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup cmdline
  * @{
  */
 

doxygen/cairo-renderer.dox

@@ -0,0 +1,4 @@
+/**
+ * @defgroup Cairo-Renderer Cairo Renderer 
+ * @ingroup renderers
+ */

doxygen/command-line.dox

@@ -0,0 +1,3 @@
+/**
+ * @defgroup cmdline Command Line Interface
+ */

doxygen/external-renderer.dox

@@ -0,0 +1,4 @@
+/**
+ * @defgroup external-renderer External Shared Object Renderer
+ * @ingroup renderers
+ */

doxygen/gui.dox

@@ -2,5 +2,4 @@
 
 /**
  * @defgroup GUI Graphical User Interface
- * @ingroup MainApplication
  */

doxygen/latex-renderer.dox

@@ -0,0 +1,4 @@
+/**
+ * @defgroup LaTeX-Renderer LaTeX/TikZ Renderer 
+ * @ingroup renderers
+ */

doxygen/layer-selector.dox

@@ -0,0 +1,7 @@
+/**
+ * @defgroup layer-selector LayerSelector Object
+ * @ingroup GUI
+ *
+ * This objects implements the layer selector and displays the layers in a list box.
+ * It uses @ref LayerElement objects to display the individual layers inside the list box. 
+ */

doxygen/lib-cell-renderer.dox

@@ -0,0 +1,18 @@
+/**
+ * @defgroup LibCellRenderer LibCellRenderer GObject
+ * @ingroup GUI
+ *
+ * The LibCellRenderer Object is used to render @ref gds_cell and @ref gds_library elements 
+ * to a GtkTreeView.
+ *
+ * The LibCellRenderer class is derived from a GtkCellRendererText and works the same way.
+ * The additinal features are three new properties:
+ *
+ * - *gds-lib*: This property can be used to set a @ref gds_library structure. The renderer will render the name of the library.
+ * - *gds-cell*: This property can be used to set a @ref gds_cell structure. The renderer will render the name of the cell.
+ * - *error-level*: Set the error level of the cell/library. This affects the foreground color of hte rendered output.
+ *
+ * Internally the class operates by setting the 'text' property, which is inherited form the base class to the library/cell name (gds_library::name and gds_cell::name fields).
+ * The error level (@ref LIB_CELL_RENDERER_ERROR_WARN and @ref LIB_CELL_RENDERER_ERROR_ERR) is translated to the inherited 'foreground-rgba' property.
+ *
+ */

doxygen/main-application.dox

@@ -1,6 +0,0 @@
-/* This file only contains help information for doxygen */
-
-/**
- * @defgroup MainApplication Main Application
- *
- */

doxygen/renderers.dox

@@ -0,0 +1,9 @@
+/**
+ * @defgroup renderers Output Renderers
+ * 
+ * The renderers are used to convert the cell structures read from the GDS layout file
+ * into different output formats.
+ * 
+ * Currently the renders are statically implemented without the use of GObjects.
+ * This will probably change in future releases in order to make it easier to integrate new rendering methods.
+ */

external-renderer.c

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup external-renderer
  * @{
  */
 

gds-render-gui.c

@@ -23,7 +23,7 @@
  * @author Mario Hüttel <mario.huettel@gmx.net>
  */
 
-/** @addtogroup MainApplication
+/** @addtogroup GUI
  * @{
  */
 
@@ -145,6 +145,7 @@ static void on_load_gds(gpointer button, gpointer user)
 						  "Open GDSII", GTK_RESPONSE_ACCEPT,
 						  NULL);
 	file_chooser = GTK_FILE_CHOOSER(open_dialog);
+
 	/* Add GDS II Filter */
 	filter = gtk_file_filter_new();
 	gtk_file_filter_add_pattern(filter, "*.gds");

include/gds-render/command-line.h

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup cmdline
  * @{
  */
 

include/gds-render/external-renderer.h

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup external-renderer
  * @{
  */
 

include/gds-render/gds-render-gui.h

@@ -27,7 +27,7 @@
 #define _GDS_RENDER_GUI_
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup GUI
  * @{
  */
 

include/gds-render/layer/layer-info.h

@@ -18,7 +18,7 @@
  */
 
 /**
- * @file layer-info.c
+ * @file layer-info.h
  * @brief Helper functions and definition of layer info struct
  * @author Mario Hüttel <mario.huettel@gmx.net>
  */

include/gds-render/layer/layer-selector.h

@@ -23,6 +23,11 @@
  * @author Mario Hüttel <mario.huettel@gmx.net>
  */
 
+/**
+ * @addtogroup layer-selector
+ * @{
+ */
+
 #ifndef __LAYER_SELECTOR_H__
 #define __LAYER_SELECTOR_H__
 
@@ -88,3 +93,5 @@ void layer_selector_force_sort(LayerSelector *selector, enum layer_selector_sort
 G_END_DECLS
 
 #endif /* __LAYER_SELECTOR_H__ */
+
+/** @} */

include/gds-render/layer/mapping-parser.h

@@ -27,7 +27,7 @@
 #define __MAPPING_PARSER_H__
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup  Mapping-Parser
  * @{
  */
 

include/gds-render/tree-renderer/lib-cell-renderer.h

@@ -17,6 +17,17 @@
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file lib-cell-renderer.h
+ * @brief Header file for the LibCellRenderer GObject Class
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
+
+/**
+ * @addtogroup LibCellRenderer
+ * @{
+ */
+
 #ifndef __LIB_CELL_RENDERER_H__
 #define __LIB_CELL_RENDERER_H__
 
@@ -27,8 +38,12 @@ G_BEGIN_DECLS
 G_DECLARE_FINAL_TYPE(LibCellRenderer, lib_cell_renderer, LIB_CELL, RENDERER, GtkCellRendererText)
 #define TYPE_LIB_CELL_RENDERER (lib_cell_renderer_get_type())
 
+/** @{
+ * Error levels
+ */
 #define LIB_CELL_RENDERER_ERROR_WARN (1U<<0)
 #define LIB_CELL_RENDERER_ERROR_ERR (1U<<1)
+/** @} */
 
 typedef struct _LibCellRenderer {
         /* Inheritance */
@@ -36,9 +51,20 @@ typedef struct _LibCellRenderer {
         /* Custom Elements */
 } LibCellRenderer;
 
+/**
+ * @brief lib_cell_renderer_get_type
+ * @return GObject Type
+ */
 GType lib_cell_renderer_get_type(void);
+
+/**
+ * @brief Create a new renderer for renderering @ref gds_cell and @ref gds_library elements.
+ * @return New renderer object
+ */
 GtkCellRenderer *lib_cell_renderer_new(void);
 
 G_END_DECLS
 
 #endif /* __LIB_CELL_RENDERER_H__ */
+
+/** @} */

include/gds-render/tree-renderer/tree-store.h

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup GUI
  * @{
  */
 

include/gds-render/version.h

@@ -18,11 +18,11 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup version
  * @{
  */
 
 /** @brief This string holds the 'git describe' version of the app */
-extern char *_app_version_string;
+extern const char *_app_version_string;
 
 /** @} */

layer/layer-info.c

@@ -23,11 +23,6 @@
  * @author Mario Hüttel <mario.huettel@gmx.net>
  */
 
-/**
- * @addtogroup MainApplication
- * @{
- */
-
 #include <gds-render/layer/layer-info.h>
 
 void layer_info_delete_struct(struct layer_info *info)
@@ -36,4 +31,3 @@ void layer_info_delete_struct(struct layer_info *info)
 		free(info);
 }
 
-/** @} */

layer/layer-selector.c

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup layer-selector
  * @{
  */
 

layer/mapping-parser.c

@@ -25,7 +25,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup Mapping-Parser
  * @{
  */
 

main.c

@@ -17,6 +17,12 @@
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file main.c
+ * @brief main.c
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
+
 #include <stdio.h>
 #include <gtk/gtk.h>
 #include <glib.h>
@@ -26,11 +32,27 @@
 #include <gds-render/external-renderer.h>
 #include <gds-render/version.h>
 
+/**
+ * @brief Structure containing The GtkApplication and a list containing the GdsRenderGui objects.
+ */
 struct application_data {
 		GtkApplication *app;
 		GList *gui_list;
 };
 
+/**
+ * @brief Callback for the menu entry 'Quit'
+ *
+ * Destroys all GUIs contained in the application_data structure
+ * provided by \p user_data.
+ *
+ * The complete suspension of all main windows leads to the termination of the
+ * GApplication.
+ *
+ * @param action unused
+ * @param parameter unused
+ * @param user_data application_data structure
+ */
 static void app_quit(GSimpleAction *action, GVariant *parameter, gpointer user_data)
 {
 	struct application_data * const appdata = (struct application_data *)user_data;
@@ -49,6 +71,15 @@ static void app_quit(GSimpleAction *action, GVariant *parameter, gpointer user_d
 	appdata->gui_list = NULL;
 }
 
+/**
+ * @brief Callback for the 'About' menu entry
+ *
+ * This function shows the about dialog.
+ *
+ * @param action GSimpleAction, unused
+ * @param parameter Unused.
+ * @param user_data Unused
+ */
 static void app_about(GSimpleAction *action, GVariant *parameter, gpointer user_data)
 {
 	GtkBuilder *builder;
@@ -83,11 +114,23 @@ static void app_about(GSimpleAction *action, GVariant *parameter, gpointer user_
 	g_object_unref(builder);
 }
 
+/**
+ * @brief Contains the application menu entries
+ */
 const static GActionEntry app_actions[] = {
 	{"quit", app_quit, NULL, NULL, NULL, {0}},
 	{"about", app_about, NULL, NULL, NULL, {0}}
 };
 
+/**
+ * @brief Called when a GUI main window is closed
+ *
+ * The GdsRenderGui object associated with the closed main window
+ * is removed from the list of open GUIs and unreferenced.
+ *
+ * @param gui The GUI instance the closed main window belongs to
+ * @param user_data List of GUIs
+ */
 static void gui_window_closed_callback(GdsRenderGui *gui, gpointer user_data)
 {
 	GList **gui_list = (GList **)user_data;
@@ -97,6 +140,11 @@ static void gui_window_closed_callback(GdsRenderGui *gui, gpointer user_data)
 	g_object_unref(gui);
 }
 
+/**
+ * @brief Activation of the GUI
+ * @param app The GApplication reference
+ * @param user_data Used to store the individual GUI instances.
+ */
 static void gapp_activate(GApplication *app, gpointer user_data)
 {
 	GtkWindow *main_window;
@@ -115,6 +163,17 @@ static void gapp_activate(GApplication *app, gpointer user_data)
 	gtk_widget_show(GTK_WIDGET(main_window));
 }
 
+/**
+ * @brief Start the graphical interface.
+ *
+ * This function starts the GUI. If there's already a
+ * running instance of this program, a second window will be
+ * created in that instance and the second one is terminated.
+ *
+ * @param argc
+ * @param argv
+ * @return
+ */
 static int start_gui(int argc, char **argv)
 {
 
@@ -160,12 +219,21 @@ static int start_gui(int argc, char **argv)
 	return app_status;
 }
 
-static void print_version()
+/**
+ * @brief Print the application version string to stdout
+ */
+static void print_version(void)
 {
 	printf("This is gds-render, version: %s\n\nFor a list of supported commands execute with --help option.\n",
 	       _app_version_string);
 }
 
+/**
+ * @brief The "entry point" of the application
+ * @param argc Number of command line parameters
+ * @param argv Command line parameters
+ * @return Execution status of the application
+ */
 int main(int argc, char **argv)
 {
 	int i;

tree-renderer/lib-cell-renderer.c

@@ -17,6 +17,17 @@
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file lib-cell-renderer.c
+ * @brief LibCellRenderer GObject Class
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
+
+/**
+ * @addtogroup LibCellRenderer
+ * @{
+ */
+
 #include <gds-render/tree-renderer/lib-cell-renderer.h>
 #include <gds-render/gds-utils/gds-types.h>
 
@@ -132,3 +143,5 @@ GtkCellRenderer *lib_cell_renderer_new()
 {
 	return GTK_CELL_RENDERER(g_object_new(TYPE_LIB_CELL_RENDERER, NULL));
 }
+
+/** @} */

tree-renderer/tree-store.c

@@ -24,7 +24,7 @@
  */
 
 /**
- * @addtogroup MainApplication
+ * @addtogroup GUI
  * @{
  */
 

version/version.c

@@ -17,8 +17,10 @@
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+
 /**
- * @addtogroup MainApplication
+ * @defgroup version Git-based Versioning Number
+ * @addtogroup version
  * @{
  */