minor fixes and doxygen Documentation started

cairo-output/cairo-output.c

@@ -16,6 +16,15 @@
  * You should have received a copy of the GNU General Public License
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
+ /**
+  * @file cairo-output.c
+  * @brief Output renderer for Cairo PDF export
+  * @author Mario Hüttel <mario.huettel@gmx.net>
+  */
+
+/** @addtogroup Cairo-Renderer
+ *  @{
+ */
 
 #include "cairo-output.h"
 #include <math.h>
@@ -23,12 +32,20 @@
 #include <cairo.h>
 #include <cairo-pdf.h>
 
+/**
+ * @brief The cairo_layer struct
+ * Each rendered layer is represented by this struct.
+ */
 struct cairo_layer {
-		cairo_t *cr;
+		cairo_t *cr; /**< @brief cairo context for layer*/
-		cairo_surface_t *rec;
+		cairo_surface_t *rec; /**< @brief Recording surface to hold the layer */
-		struct layer_info *linfo;
+		struct layer_info *linfo; /**< @brief Reference to layer information */
 };
 
+/**
+ * @brief Revert the last transformation on all layers
+ * @param layers Pointer to #cairo_layer structures
+ */
 static void revert_inherited_transform(struct cairo_layer *layers)
 {
 	int i;
@@ -40,6 +57,15 @@ static void revert_inherited_transform(struct cairo_layer *layers)
 	}
 }
 
+/**
+ * @brief Applies transformation to all layers
+ * @param layers Array of layers
+ * @param origin Origin translation
+ * @param magnification Scaling
+ * @param flipping Mirror image on x-axis before rotating
+ * @param rotation Rotattion in degrees
+ * @param scale Scale the image down by. Only used for sclaing origin coordinates. Not applied to layer.
+ */
 static void apply_inherited_transform_to_all_layers(struct cairo_layer *layers,
 						    const struct gds_point *origin,
 						    double magnification,
@@ -64,6 +90,12 @@ static void apply_inherited_transform_to_all_layers(struct cairo_layer *layers,
 	}
 }
 
+/**
+ * @brief render_cell Render a cell with its sub-cells
+ * @param cell Cell to render
+ * @param layers Cell will be rendered into these layers
+ * @param scale sclae image down by this factor
+ */
 static void render_cell(struct gds_cell *cell, struct cairo_layer *layers, double scale)
 {
 	GList *instance_list;
@@ -246,3 +278,5 @@ ret_clear_layers:
 
 	printf("cairo export finished. It might still be buggy!\n");
 }
+
+/** @} */

cairo-output/cairo-output.h

@@ -16,15 +16,32 @@
  * You should have received a copy of the GNU General Public License
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/**
+ * @file cairo-output.h
+ * @brief Header File for Cairo output renderer
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
 #ifndef __CAIRO_OUTPUT_H__
 #define __CAIRO_OUTPUT_H__
 
 #include "../layer-selector.h"
 #include "../gds-parser/gds-types.h"
 
-#define MAX_LAYERS (300)
+/** @addtogroup Cairo-Renderer
+ *  @{
+ */
 
+#define MAX_LAYERS (300) /**< \brief Maximum layer count the output renderer can process. Typically GDS only specifies up to 255 layers.*/
+
+/**
+ * @brief Render \p cell to a PDF file specified by \p pdf_file
+ * @param cell Toplevel cell to render
+ * @param layer_infos List of layer information. Specifies color and layer stacking
+ * @param pdf_file Output file
+ * @param scale Scale the output image down by \p scale
+ */
 void cairo_render_cell_to_pdf(struct gds_cell *cell, GList *layer_infos, char *pdf_file, double scale);
 
+/** @} */
+
 #endif /* __CAIRO_OUTPUT_H__ */

doxygen/Doxyconfig

@@ -454,7 +454,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -865,7 +865,7 @@ FILE_PATTERNS          = *.c \
 # be searched for input files as well.
 # The default value is: NO.
 
-RECURSIVE              = NO
+RECURSIVE              = YES
 
 # The EXCLUDE tag can be used to specify files and/or directories that should be
 # excluded from the INPUT source files. This way you can easily exclude a

gds-parser/gds-parser.c

@@ -18,14 +18,27 @@
  */
 
 /*
+
+ */
+
+
+/**
+ * @file gds_parser.h
+ * @brief Header file for the GDS-Parser
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ *
  * What's missing? - A lot:
- * Support for Boxes
  * Support for 4 Byte real
  * Support for pathtypes
  * Support for datatypes (only layer so far)
  * etc...
  */
 
+/**
+ * @addtogroup GDS-Parser
+ * @{
+ */
+
 
 #include "gds-parser.h"
 #include <stdlib.h>
@@ -35,10 +48,10 @@
 #include <math.h>
 #include <cairo.h>
 
-#define GDS_ERROR(fmt, ...) printf("[PARSE_ERROR] " fmt "\n", ##__VA_ARGS__)
+#define GDS_ERROR(fmt, ...) printf("[PARSE_ERROR] " fmt "\n", ##__VA_ARGS__) /**< @brief Print GDS error*/
-#define GDS_WARN(fmt, ...) printf("[PARSE_WARNING] " fmt "\n", ##__VA_ARGS__)
+#define GDS_WARN(fmt, ...) printf("[PARSE_WARNING] " fmt "\n", ##__VA_ARGS__) /**< @brief Print GDS warning */
 
-enum record {
+enum gds_record {
 	INVALID = 0x0000,
 	HEADER = 0x0002,
 	BGNLIB = 0x0102,
@@ -63,6 +76,13 @@ enum record {
 	PATHTYPE = 0x2102
 };
 
+/**
+ * @brief Name cell reference
+ * @param cell_inst Cell reference
+ * @param bytes Length of name
+ * @param data Name
+ * @return 0 if successful
+ */
 static int name_cell_ref(struct gds_cell_instance *cell_inst,
 			 unsigned int bytes, char *data)
 {
@@ -73,7 +93,7 @@ static int name_cell_ref(struct gds_cell_instance *cell_inst,
 		return -1;
 	}
 	data[bytes] = 0; // Append '0'
-	len = strlen(data);
+	len = (int)strlen(data);
 	if (len > CELL_NAME_MAX-1) {
 		GDS_ERROR("Cell name '%s' too long: %d\n", data, len);
 		return -1;
@@ -86,6 +106,11 @@ static int name_cell_ref(struct gds_cell_instance *cell_inst,
 	return 0;
 }
 
+/**
+ * @brief Convert GDS 8-byte real to double
+ * @param data 8 Byte GDS real
+ * @return result
+ */
 static double gds_convert_double(const char *data)
 {
 	bool sign_bit;
@@ -126,6 +151,11 @@ static double gds_convert_double(const char *data)
 	return ret_val;
 }
 
+/**
+ * @brief Convert GDS INT32 to int
+ * @param data Buffer containing the int
+ * @return result
+ */
 static signed int gds_convert_signed_int(const char *data)
 {
 	int ret;
@@ -142,6 +172,11 @@ static signed int gds_convert_signed_int(const char *data)
 	return ret;
 }
 
+/**
+ * @brief Convert GDS INT16 to int16
+ * @param data Buffer containing the INT16
+ * @return result
+ */
 static int16_t gds_convert_signed_int16(const char *data)
 {
 	if (!data) {
@@ -152,6 +187,11 @@ static int16_t gds_convert_signed_int16(const char *data)
 			(((int16_t)(data[1]) & 0xFF) <<  0));
 }
 
+/**
+ * @brief Convert GDS UINT16 String to uint16
+ * @param data Buffer containing the uint16
+ * @return result
+ */
 static uint16_t gds_convert_unsigend_int16(const char *data)
 {
 	if (!data) {
@@ -162,6 +202,12 @@ static uint16_t gds_convert_unsigend_int16(const char *data)
 			(((uint16_t)(data[1]) & 0xFF) <<  0));
 }
 
+/**
+ * @brief Append library to list
+ * @param curr_list List containing gds_library elements. May be NULL.
+ * @param library_ptr Return of newly created library.
+ * @return Newly created list pointer
+ */
 static GList *append_library(GList *curr_list, struct gds_library **library_ptr)
 {
 	struct gds_library *lib;
@@ -180,6 +226,13 @@ static GList *append_library(GList *curr_list, struct gds_library **library_ptr)
 	return g_list_append(curr_list, lib);
 }
 
+/**
+ * @brief Append graphics to list
+ * @param curr_list List containing gds_graphics elements. May be NULL
+ * @param type Type of graphics
+ * @param graphics_ptr newly created graphic is written here
+ * @return new list pointer
+ */
 static GList *append_graphics(GList *curr_list, enum graphics_type type,
 			      struct gds_graphics **graphics_ptr)
 {
@@ -202,6 +255,13 @@ static GList *append_graphics(GList *curr_list, enum graphics_type type,
 	return g_list_append(curr_list, gfx);
 }
 
+/**
+ * @brief Appends vertext List
+ * @param curr_list List containing gds_point elements. May be NULL.
+ * @param x x-coordinate of new point
+ * @param y y-coordinate of new point
+ * @return new Pointer to List.
+ */
 static GList *append_vertex(GList *curr_list, int x, int y)
 {
 	struct gds_point *vertex;
@@ -215,6 +275,14 @@ static GList *append_vertex(GList *curr_list, int x, int y)
 	return g_list_append(curr_list, vertex);
 }
 
+/**
+ * @brief append_cell Append a gds_cell to a list
+ *
+ * Usage similar to append_cell_ref().
+ * @param curr_list List containing gds_cell elements. May be NULL
+ * @param cell_ptr newly created cell
+ * @return new pointer to list
+ */
 static GList *append_cell(GList *curr_list, struct gds_cell **cell_ptr)
 {
 	struct gds_cell *cell;
@@ -233,6 +301,14 @@ static GList *append_cell(GList *curr_list, struct gds_cell **cell_ptr)
 	return g_list_append(curr_list, cell);
 }
 
+/**
+ * @brief Append a cell reference to the reference GList.
+ *
+ * Appends a new gds_cell_instance to \p curr_list and returns the new element via \p instance_ptr
+ * @param curr_list List of gds_cell_instance elements. May be NULL
+ * @param instance_ptr newly created element
+ * @return new GList pointer
+ */
 static GList *append_cell_ref(GList *curr_list, struct gds_cell_instance **instance_ptr)
 {
 	struct gds_cell_instance *inst;
@@ -254,6 +330,13 @@ static GList *append_cell_ref(GList *curr_list, struct gds_cell_instance **insta
 	return g_list_append(curr_list, inst);
 }
 
+/**
+ * @brief Name a gds_library
+ * @param current_library Library to name
+ * @param bytes Lenght of name
+ * @param data Name
+ * @return 0 if successful
+ */
 static int name_library(struct gds_library *current_library,
 			unsigned int bytes, char *data)
 {
@@ -265,7 +348,7 @@ static int name_library(struct gds_library *current_library,
 	}
 
 	data[bytes] = 0; // Append '0'
-	len = strlen(data);
+	len = (int)strlen(data);
 	if (len > CELL_NAME_MAX-1) {
 		GDS_ERROR("Library name '%s' too long: %d\n", data, len);
 		return -1;
@@ -277,6 +360,14 @@ static int name_library(struct gds_library *current_library,
 	return 0;
 }
 
+/**
+ * @brief Names a gds_cell
+ * @param cell Cell to name
+ * @param bytes Length of name
+ * @param data Name
+ * @param lib Library in which \p cell is located
+ * @return 0 id successful
+ */
 static int name_cell(struct gds_cell *cell, unsigned int bytes,
 		     char *data, struct gds_library *lib)
 {
@@ -302,7 +393,13 @@ static int name_cell(struct gds_cell *cell, unsigned int bytes,
 	return 0;
 }
 
-
+/**
+ * @brief Search for cell reference \p gcell_ref in \p glibrary
+ *
+ * Search cell referenced by \p gcell_ref inside \p glibrary and update gds_cell_instance::cell_ref with found #gds_cell
+ * @param gcell_ref gpointer cast of struct gds_cell_instance *
+ * @param glibrary gpointer cast of struct gds_library *
+ */
 static void parse_reference_list(gpointer gcell_ref, gpointer glibrary)
 {
 	struct gds_cell_instance *inst = (struct gds_cell_instance *)gcell_ref;
@@ -329,6 +426,12 @@ static void parse_reference_list(gpointer gcell_ref, gpointer glibrary)
 	GDS_WARN("referenced cell could not be found in library");
 }
 
+/**
+ * @brief Scans cell references inside cell
+ This function searches all the references in \p gcell and updates the gds_cell_instance::cell_ref field in each instance
+ * @param gcell pointer cast of #gds_cell *
+ * @param library Library where the cell references are searched in
+ */
 static void scan_cell_reference_dependencies(gpointer gcell, gpointer library)
 {
 	struct gds_cell *cell = (struct gds_cell *)gcell;
@@ -340,6 +443,13 @@ static void scan_cell_reference_dependencies(gpointer gcell, gpointer library)
 
 }
 
+/**
+ * @brief Scans library's cell references
+ *
+ * This function searches all the references between cells and updates the gds_cell_instance::cell_ref field in each instance
+ * @param library_list_item List containing #gds_library elements
+ * @param user not used
+ */
 static void scan_library_references(gpointer library_list_item, gpointer user)
 {
 	struct gds_library *lib = (struct gds_library *)library_list_item;
@@ -348,6 +458,13 @@ static void scan_library_references(gpointer library_list_item, gpointer user)
 	g_list_foreach(lib->cells, scan_cell_reference_dependencies, lib);
 }
 
+/**
+ * @brief gds_parse_date
+ * @param buffer Buffer that contains the GDS Date field
+ * @param length Length of \p buffer
+ * @param mod_date Modification Date
+ * @param access_date Last Access Date
+ */
 static void gds_parse_date(const char *buffer, int length, struct gds_time_field *mod_date, struct gds_time_field *access_date)
 {
 
@@ -390,7 +507,7 @@ int parse_gds_from_file(const char *filename, GList **library_list)
 	int run = 1;
 	FILE *gds_file = NULL;
 	uint16_t rec_data_length;
-	enum record rec_type;
+	enum gds_record rec_type;
 	struct gds_library *current_lib = NULL;
 	struct gds_cell *current_cell = NULL;
 	struct gds_graphics *current_graphics = NULL;
@@ -628,10 +745,10 @@ int parse_gds_from_file(const char *filename, GList **library_list)
 			gds_parse_date(workbuff, read, &current_cell->mod_time, &current_cell->access_time);
 			break;
 		case LIBNAME:
-			name_library(current_lib, read, workbuff);
+			name_library(current_lib, (unsigned int)read, workbuff);
 			break;
 		case STRNAME:
-			name_cell(current_cell, read, workbuff, current_lib);
+			name_cell(current_cell, (unsigned int)read, workbuff, current_lib);
 			break;
 		case XY:
 			if (current_s_reference) {
@@ -742,22 +859,38 @@ int parse_gds_from_file(const char *filename, GList **library_list)
 	return run;
 }
 
+/**
+ * @brief delete_cell_inst_element
+ * @param cell_inst
+ */
 static void delete_cell_inst_element(struct gds_cell_instance *cell_inst)
 {
 	free(cell_inst);
 }
 
+/**
+ * @brief delete_vertex
+ * @param vertex
+ */
 static void delete_vertex(struct gds_point *vertex)
 {
 	free(vertex);
 }
 
+/**
+ * @brief delete_graphics_obj
+ * @param gfx
+ */
 static void delete_graphics_obj(struct gds_graphics *gfx)
 {
 	g_list_free_full(gfx->vertices, (GDestroyNotify)delete_vertex);
 	free(gfx);
 }
 
+/**
+ * @brief delete_cell_element
+ * @param cell
+ */
 static void delete_cell_element(struct gds_cell *cell)
 {
 	g_list_free_full(cell->child_cells, (GDestroyNotify)delete_cell_inst_element);
@@ -765,6 +898,10 @@ static void delete_cell_element(struct gds_cell *cell)
 	free(cell);
 }
 
+/**
+ * @brief delete_library_element
+ * @param lib
+ */
 static void delete_library_element(struct gds_library *lib)
 {
 	g_list_free(lib->cell_names);
@@ -780,3 +917,5 @@ int clear_lib_list(GList **library_list)
 	*library_list = NULL;
 	return 0;
 }
+
+/** @} */

gds-parser/gds-parser.h

@@ -17,6 +17,17 @@
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file gds_parser.h
+ * @brief Header file for the GDS-Parser
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
+
+/**
+ * @addtogroup GDS-Parser
+ * @{
+ */
+
 #ifndef __GDSPARSE_H__
 #define __GDSPARSE_H__
 
@@ -24,6 +35,13 @@
 #include "gds-types.h"
 
 int parse_gds_from_file(const char *filename, GList **library_array);
+/**
+ * @brief Deletes all libraries including cells, references etc.
+ * @param Pointer to a list of #gds_library. Is set to NULL after completion.
+ * @return 0
+ */
 int clear_lib_list(GList **library_list);
 
+/** @} */
+
 #endif /* __GDSPARSE_H__ */

gds-parser/gds-types.h

@@ -1,21 +1,67 @@
+/*
+ * GDSII-Converter
+ * Copyright (C) 2018  Mario Hüttel <mario.huettel@gmx.net>
+ *
+ * This file is part of GDSII-Converter.
+ *
+ * GDSII-Converter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * GDSII-Converter is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @file gds-types.h
+ * @brief Defines types and macros used by the GDS-Parser
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
+
+/**
+  * @addtogroup GDS-Parser
+  * @{
+  */
+
 #ifndef __GDS_TYPES_H__
 #define __GDS_TYPES_H__
 
 #include <stdint.h>
 #include <glib.h>
 
-#define CELL_NAME_MAX (100)
+#define CELL_NAME_MAX (100) /**< @brief Maximum length of a gds_cell::name or a gds_library::name */
-#define MIN(a,b) (((a) < (b)) ? (a) : (b))
+#define MIN(a,b) (((a) < (b)) ? (a) : (b)) /**< @brief Find return smaller number */
-#define MAX(a,b) (((a) > (b)) ? (a) : (b))
+#define MAX(a,b) (((a) > (b)) ? (a) : (b)) /**< @brief Find return bigger number */
 
-enum graphics_type {GRAPHIC_PATH = 0, GRAPHIC_POLYGON = 1, GRAPHIC_BOX};
+/** @brief Types of graphic objects */
-enum path_type {PATH_FLUSH = 0, PATH_ROUNDED = 1, PATH_SQUARED = 2};
+enum graphics_type
+{
+		    GRAPHIC_PATH = 0, /**< @brief Path. Esentially a line */
+		    GRAPHIC_POLYGON = 1, /**< @brief An arbitrary polygon */
+		    GRAPHIC_BOX = 2 /**< @brief A rectangle. @warning Implementation in renderers might be buggy!*/
+};
 
+/**
+ * @brief Defines the line caps of a path
+ */
+enum path_type {PATH_FLUSH = 0, PATH_ROUNDED = 1, PATH_SQUARED = 2}; /**< Path line caps */
+
+/**
+ * @brief A point in the 2D plane. Sometimes references as vertex
+ */
 struct gds_point {
 	int x;
 	int y;
 };
 
+/**
+ * @brief Date information for cells and libraries
+ */
 struct gds_time_field {
 	uint16_t year;
 	uint16_t month;
@@ -25,39 +71,53 @@ struct gds_time_field {
 	uint16_t second;
 };
 
+/**
+ * @brief A GDS graphics object
+ */
 struct gds_graphics {
-	enum graphics_type gfx_type;
+	enum graphics_type gfx_type; /**< \brief Type of graphic */
-	GList *vertices;
+	GList *vertices; /**< @brief List of #gds_point */
-	enum path_type path_render_type;
+	enum path_type path_render_type; /**< @brief Line cap */
-	int width_absolute;
+	int width_absolute; /**< @brief Width. Not used for objects other than paths */
-	int16_t layer;
+	int16_t layer; /**< @brief Layer the graphic object is on */
 	uint16_t datatype;
 };
 
+/**
+ * @brief This represents an instanc of a cell inside another cell
+ */
 struct gds_cell_instance {
-	char ref_name[CELL_NAME_MAX];
+	char ref_name[CELL_NAME_MAX]; /**< @brief Name of referenced cell */
-	struct gds_cell *cell_ref;
+	struct gds_cell *cell_ref; /**< @brief Referenced gds_cell structure */
-	struct gds_point origin;
+	struct gds_point origin; /**< @brief Origin */
-	int flipped;
+	int flipped; /**< @brief Mirrored on x-axis before rotation */
-	double angle;
+	double angle; /**< @brief Angle of rotation (counter clockwise) in degrees */
-	double magnification;
+	double magnification; /**< @brief magnification */
 };
 
+/**
+ * @brief A Cell inside a gds_library
+ */
 struct gds_cell {
 	char name[CELL_NAME_MAX];
 	struct gds_time_field mod_time;
 	struct gds_time_field access_time;
-	GList *child_cells;
+	GList *child_cells; /**< @brief List of #gds_cell_instance elements */
-	GList *graphic_objs;
+	GList *graphic_objs; /**< @brief List of #gds_graphics */
 };
 
+/**
+ * @brief GDS Toplevel library
+ */
 struct gds_library {
 	char name[CELL_NAME_MAX];
 	struct gds_time_field mod_time;
 	struct gds_time_field access_time;
-	double unit_to_meters;
+	double unit_to_meters;  /**< @warning not yet implemented */
-	GList *cells;
+	GList *cells; /**< List of #gds_cell that contains all cells in this library*/
-	GList *cell_names;
+	GList *cell_names /**< List of strings that contains all cell names */;
 };
 
+/** @} */
+
 #endif /* __GDS_TYPES_H__ */

latex-output/latex-output.h

@@ -17,17 +17,39 @@
  * along with GDSII-Converter.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file latex-output.h
+ * @brief LaTeX output renderer
+ * @author Mario Hüttel <mario.huettel@gmx.net>
+ */
+
 #ifndef __LATEX_OUTPUT_H__
 #define __LATEX_OUTPUT_H__
 
+/**
+ * @addtogroup LaTeX-Renderer
+ * @{
+ */
+
 #include "../gds-parser/gds-types.h"
 #include <glib.h>
 #include <stdio.h>
 #include "../layer-selector.h"
 
-#define LATEX_LINE_BUFFER_KB (10)
+#define LATEX_LINE_BUFFER_KB (10) /**< @brief Buffer for LaTeX Code line in KiB */
 
+/**
+ * @brief Render \p cell to LateX/TikZ code
+ * @param cell Cell to render
+ * @param layer_infos Layer information
+ * @param tex_file Already opened file to write data in
+ * @param scale Scale image down by this value
+ * @param create_pdf_layers Optional content groups used
+ * @param standalone_document document can be compiled standalone
+ */
 void latex_render_cell_to_code(struct gds_cell *cell, GList *layer_infos, FILE *tex_file, double scale,
 			       gboolean create_pdf_layers, gboolean standalone_document);
 
+/** @} */
+
 #endif /* __LATEX_OUTPUT_H__ */