[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
gEDA-cvs: gaf.git: branch: master updated (1.5.2-20090328-125-g633766c)
The branch, master has been updated
via 633766c156acc8fcca4a34c619f63b773eccce2e (commit)
from 1f05fb8e7b857c2bba2fbcaa4893ecbedcc478a9 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
=========
Summary
=========
gattrib/include/globals.h | 40 +++++---
gattrib/include/i_vars.h | 6 +
gattrib/include/prototype.h | 2 +-
gattrib/include/struct.h | 108 ++++++++++++--------
gattrib/src/f_export.c | 16 ++-
gattrib/src/g_rc.c | 14 +++-
gattrib/src/g_register.c | 16 +++-
gattrib/src/gattrib.c | 162 ++++++++++++++++++++++++------
gattrib/src/globals.c | 18 +++-
gattrib/src/i_basic.c | 6 +-
gattrib/src/i_vars.c | 25 ++++-
gattrib/src/listsort.c | 30 +++++--
gattrib/src/parsecmd.c | 33 ++++++-
gattrib/src/s_attrib.c | 35 +++++--
gattrib/src/s_misc.c | 29 +++++-
gattrib/src/s_object.c | 110 ++++++++++++++-------
gattrib/src/s_rename.c | 47 ++++++++-
gattrib/src/s_sheet_data.c | 125 +++++++++++++----------
gattrib/src/s_string_list.c | 143 ++++++++++++++++-----------
gattrib/src/s_table.c | 114 ++++++++++++++++------
gattrib/src/s_toplevel.c | 228 +++++++++++++++++++++++++------------------
gattrib/src/s_visibility.c | 61 ++++++++----
gattrib/src/x_dialog.c | 45 ++++++---
gattrib/src/x_fileselect.c | 32 ++++--
gattrib/src/x_gtksheet.c | 77 +++++++++++---
gattrib/src/x_window.c | 79 +++++++++++----
26 files changed, 1108 insertions(+), 493 deletions(-)
=================
Commit Messages
=================
commit 633766c156acc8fcca4a34c619f63b773eccce2e
Author: Gareth Edwards <gareth@xxxxxxxxxxxxxxxxxxxx>
Commit: Peter TB Brett <peter@xxxxxxxxxxxxx>
gattrib: many doxygen comment improvements
- Cleaned up brief descriptions for functions and added full
descriptions, parameter descriptions and return values for the
functions in gattrib.c
- Added a mainpage for doxygen, including SDB's notes from the comment
block in the file itself, plus the notes from the mailing list
message SDB sent to Ivan when he was intending to work on gattrib
- Made a lot of doxygen improvements in parsecmd.c. All functions
documented plus the OPTIONS defined.
- Doxygen commenting in s_sheet_data.c Documented the s_sheet_new()
function and the file itself in s_sheet_data.c.
- Added file block to parsecmd.c, remove redundant
argument to file command in s_sheet_data.c and s_string_list.c
- Added Doxygen comments for the st_string_list struct.
- doxygen commeted listsort.c, Added doxygen link from main() to
gattrib_main(). Added the brackets required by doxygen in the
comment for main() to allow it to automatically link to the
documentation for the gattrib_main() function. Added a note to
listsort.c expressing my desire to merge it into
s_string_list.c. Also noted that it might use some optimisation for
STRING_LIST specifics.
- doxygen comments for s_toplevel.c. Added doxygen comments for
globals.h, prototype.h, g_rc.c, g_register.c and i_basic.c. Added
doxygen comments to i_vars.h, i_vars.c, s_attrib.c, s_misc.c and
s_object.c. Added doxygen comments to s_rename.c and s_table.c
- Added doxygen comments to s_visibility.c,
x_dialog.c and x_fileselect.c.
- Added more doxygen commenting to x_gtksheet.c Added doxygen comments
to x_window.c Noted in the doxygen commentary for s_string_list that
the structures in that file would be equally well served by a GList
structure, which would allow the use of the glib sort and search
routines, instead of the homebrew ones in this file. Added the
correct tagging to struct.h to push the comments into the doxygen
output. Improved doxygen comments in s_table.c
:100644 100644 6efe0c7... e8c1255... M gattrib/include/globals.h
:100644 100644 1b84d26... 4f128c7... M gattrib/include/i_vars.h
:100644 100644 4745506... 4895461... M gattrib/include/prototype.h
:100644 100644 2d2af10... 283b791... M gattrib/include/struct.h
:100644 100644 03d011a... c1245f7... M gattrib/src/f_export.c
:100644 100644 7f2e158... dd3b0a1... M gattrib/src/g_rc.c
:100644 100644 aff0dc5... 9662ada... M gattrib/src/g_register.c
:100644 100644 0e24500... 2c2ac47... M gattrib/src/gattrib.c
:100644 100644 9a8185c... 65d497c... M gattrib/src/globals.c
:100644 100644 a3787a4... 513b5ad... M gattrib/src/i_basic.c
:100644 100644 4b4573d... 02eb49b... M gattrib/src/i_vars.c
:100644 100644 d5948f9... 8e7dfa6... M gattrib/src/listsort.c
:100644 100644 015435e... 352a1d7... M gattrib/src/parsecmd.c
:100644 100644 5f69e9c... 615bde8... M gattrib/src/s_attrib.c
:100644 100644 cfa2fe3... 9259041... M gattrib/src/s_misc.c
:100644 100644 8c84995... db9ccd2... M gattrib/src/s_object.c
:100644 100644 a5b5dc8... 868b046... M gattrib/src/s_rename.c
:100644 100644 3f8996d... 4154bf5... M gattrib/src/s_sheet_data.c
:100644 100644 d5e4760... b56dc6f... M gattrib/src/s_string_list.c
:100644 100644 25fca77... 47bbe80... M gattrib/src/s_table.c
:100644 100644 c76385e... 05c27b0... M gattrib/src/s_toplevel.c
:100644 100644 e35b63c... 083ca5f... M gattrib/src/s_visibility.c
:100644 100644 9766634... 5030788... M gattrib/src/x_dialog.c
:100644 100644 04a9184... e7eeca1... M gattrib/src/x_fileselect.c
:100644 100644 ec7e949... 2996a6f... M gattrib/src/x_gtksheet.c
:100644 100644 62173bf... 4bf3cfe... M gattrib/src/x_window.c
=========
Changes
=========
commit 633766c156acc8fcca4a34c619f63b773eccce2e
Author: Gareth Edwards <gareth@xxxxxxxxxxxxxxxxxxxx>
Commit: Peter TB Brett <peter@xxxxxxxxxxxxx>
gattrib: many doxygen comment improvements
- Cleaned up brief descriptions for functions and added full
descriptions, parameter descriptions and return values for the
functions in gattrib.c
- Added a mainpage for doxygen, including SDB's notes from the comment
block in the file itself, plus the notes from the mailing list
message SDB sent to Ivan when he was intending to work on gattrib
- Made a lot of doxygen improvements in parsecmd.c. All functions
documented plus the OPTIONS defined.
- Doxygen commenting in s_sheet_data.c Documented the s_sheet_new()
function and the file itself in s_sheet_data.c.
- Added file block to parsecmd.c, remove redundant
argument to file command in s_sheet_data.c and s_string_list.c
- Added Doxygen comments for the st_string_list struct.
- doxygen commeted listsort.c, Added doxygen link from main() to
gattrib_main(). Added the brackets required by doxygen in the
comment for main() to allow it to automatically link to the
documentation for the gattrib_main() function. Added a note to
listsort.c expressing my desire to merge it into
s_string_list.c. Also noted that it might use some optimisation for
STRING_LIST specifics.
- doxygen comments for s_toplevel.c. Added doxygen comments for
globals.h, prototype.h, g_rc.c, g_register.c and i_basic.c. Added
doxygen comments to i_vars.h, i_vars.c, s_attrib.c, s_misc.c and
s_object.c. Added doxygen comments to s_rename.c and s_table.c
- Added doxygen comments to s_visibility.c,
x_dialog.c and x_fileselect.c.
- Added more doxygen commenting to x_gtksheet.c Added doxygen comments
to x_window.c Noted in the doxygen commentary for s_string_list that
the structures in that file would be equally well served by a GList
structure, which would allow the use of the glib sort and search
routines, instead of the homebrew ones in this file. Added the
correct tagging to struct.h to push the comments into the doxygen
output. Improved doxygen comments in s_table.c
diff --git a/gattrib/include/globals.h b/gattrib/include/globals.h
index 6efe0c7..e8c1255 100644
--- a/gattrib/include/globals.h
+++ b/gattrib/include/globals.h
@@ -18,31 +18,36 @@
*/
-/* ----------- SDB note about philosophy behind globals -------------- *
+/*!
+ * \file
+ * \brief Global variable declarations
+ *
+ * \section sdb_note SDB note about philosophy behind globals
+ *
* I made the "TOPLEVEL project" and all the GTK window stuff into
* global variables. I know that this is supposedly bad programming form.
* However, here are some observations:
- * -- I wanted to use gEDA's TOPLEVEL structure as much as possible, at
+ * - I wanted to use gEDA's TOPLEVEL structure as much as possible, at
* least to hold info about the design's netlist & components.
* The TOPLEVEL strucuture is architected to hold info about gschem's
* window also. HOwever, gschem's windows are architected differently
* than mine in gattrib. This is because my windowing system does
* completely different things, and also uses the GtkSheet widget, which
* is architected completely differently from TOPLEVEL.
- * -- Since I couldn't easily or naturally cram my windowing scheme into
+ * - Since I couldn't easily or naturally cram my windowing scheme into
* TOPLEVEL (or so I think), I decided to use a separate set of windows
* from those defined under TOPLEVEL for my application.
- * -- The problem arises when using callbacks. Callbacks from GTK allow
+ * - The problem arises when using callbacks. Callbacks from GTK allow
* only one argument to be passed. Given the way I set up the menu bar,
* I didn't have easy acces to the information inside both the GtkSHeet
* objects *and* the TOPLEVEL stuff while only having one callback
* argument. This makes it hard to have access to e.g. a GtkSheet window
* and a list of files (in TOPLEVEL) simultaneously.
- * -- Therefore, I decided to make both the window stuff and TOPLEVEL
+ * - Therefore, I decided to make both the window stuff and TOPLEVEL
* globals.
- * -- Similarly, because I couldn't cram the SHEET_DATA struct into any
+ * - Similarly, because I couldn't cram the SHEET_DATA struct into any
* hook in TOPLEVEL, I just made it a global also.
- * -- Finally, in my defense, in gschem and gnetlist, (TOPLEVEL *w_current
+ * - Finally, in my defense, in gschem and gnetlist, (TOPLEVEL *w_current
* or pr_current) is passed to almost every function. Since it
* is just a pointer to a huge struct of stuff, manipulating
* the stuff in the struct has a global
@@ -54,25 +59,32 @@
* problem here. Therefore, I decided
* to make life easy for myself dealing with callbacks by making both
* the windows and TOPLEVEL global variables.
+ *
* If there is a better way to solve this problem, I'd like to hear it.
- * ------------------------------------------------------------------ */
+ *
+ */
+/* ------------------------------------------------------------------ */
#ifndef __GLOBALS__
#define __GLOBALS__
-/*------------------------------------------------------------------
- * pr_current -- the main data structure from gEDA. I made it a
+/*------------------------------------------------------------------*/
+/*!
+ * The main data structure from gEDA. I made it a
* global since it was treated that way anyway. It is defined in
* structs.h
- *------------------------------------------------------------------*/
+ */
+/*------------------------------------------------------------------*/
TOPLEVEL *pr_current;
-/*------------------------------------------------------------------
- * (SHEET_DATA *sheet_head) -- my own data structure which I made
+/*------------------------------------------------------------------*/
+/*!
+ * My own data structure which I made
* a global because it was easier to deal with when handing
* callbacks. It is defined in structs.h
- *------------------------------------------------------------------*/
+ */
+/*------------------------------------------------------------------*/
SHEET_DATA *sheet_head;
/*------------------------------------------------------------------
diff --git a/gattrib/include/i_vars.h b/gattrib/include/i_vars.h
index 1b84d26..4f128c7 100644
--- a/gattrib/include/i_vars.h
+++ b/gattrib/include/i_vars.h
@@ -17,6 +17,12 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*!
+ * \file
+ * \brief Default variable value declarations.
+ * Default variable value declarations.
+ */
+
extern int default_text_size;
extern int default_text_caps;
diff --git a/gattrib/include/prototype.h b/gattrib/include/prototype.h
index 4745506..4895461 100644
--- a/gattrib/include/prototype.h
+++ b/gattrib/include/prototype.h
@@ -1,4 +1,4 @@
-/*
+/*! \file
* This file holds all function prototypes for the entire gattrib
* project. It should be #include'ed after struct.h.
*/
diff --git a/gattrib/include/struct.h b/gattrib/include/struct.h
index 2d2af10..283b791 100644
--- a/gattrib/include/struct.h
+++ b/gattrib/include/struct.h
@@ -17,9 +17,13 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/* ----------------------------------------------------------------- *
+/* ----------------------------------------------------------------- */
+/*! \file
+ * \brief Definitions of structures used in gattrib
+ *
* This file holds definitions of the structures used in gattrib.
- * ----------------------------------------------------------------- */
+ */
+/* ----------------------------------------------------------------- */
#ifndef SHEET_DATA_STRUCT
@@ -54,85 +58,103 @@ typedef struct st_pin_list PIN_LIST;
typedef struct st_main_window MAIN_WINDOW;
-/* -------------------------------------------------------------------- *
+/* -------------------------------------------------------------------- */
+/*! \brief Sheet data structure
+ *
* st_sheet_data defines SHEET_DATA, and holds master lists holding
* sorted lists of comp/netlist names. Also holds pointers to the heads
* of the attribute-holding component and net structures.
- * -------------------------------------------------------------------- */
+ */
+/* -------------------------------------------------------------------- */
struct st_sheet_data {
- STRING_LIST *master_comp_list_head; /* Sorted list of all component refdeses used in design */
- STRING_LIST *master_comp_attrib_list_head; /* Sorted list of all component attribs used in design */
- int comp_count; /* This cannnot change -- user must edit design using gschem */
- int comp_attrib_count; /* This can change in this prog if the user adds attribs */
+ STRING_LIST *master_comp_list_head; /*!< Sorted list of all component refdeses used in design */
+ STRING_LIST *master_comp_attrib_list_head; /*!< Sorted list of all component attribs used in design */
+ int comp_count; /*!< This cannnot change -- user must edit design using gschem */
+ int comp_attrib_count; /*!< This can change in this prog if the user adds attribs */
- STRING_LIST *master_net_list_head; /* Sorted list of all net names used in design */
- STRING_LIST *master_net_attrib_list_head; /* Sorted list of all net attribs used in design */
- int net_count; /* This cannnot change -- user must edit design using gschem */
- int net_attrib_count; /* This can change in this prog if the user adds attribs */
+ STRING_LIST *master_net_list_head; /*!< Sorted list of all net names used in design */
+ STRING_LIST *master_net_attrib_list_head; /*!< Sorted list of all net attribs used in design */
+ int net_count; /*!< This cannnot change -- user must edit design using gschem */
+ int net_attrib_count; /*!< This can change in this prog if the user adds attribs */
- STRING_LIST *master_pin_list_head; /* Sorted list of all refdes:pin items used in design. */
- STRING_LIST *master_pin_attrib_list_head; /* Sorted list of all pin attribs used in design */
- int pin_count; /* This cannnot change -- user must edit design using gschem */
- int pin_attrib_count; /* This can change in this prog if the user adds attribs */
+ STRING_LIST *master_pin_list_head; /*!< Sorted list of all refdes:pin items used in design. */
+ STRING_LIST *master_pin_attrib_list_head; /*!< Sorted list of all pin attribs used in design */
+ int pin_count; /*!< This cannnot change -- user must edit design using gschem */
+ int pin_attrib_count; /*!< This can change in this prog if the user adds attribs */
- TABLE **component_table; /* points to 2d array of component attribs */
- TABLE **net_table; /* points to 2d array of net attribs */
- TABLE **pin_table; /* points to 2d array of pin attribs */
+ TABLE **component_table; /*!< points to 2d array of component attribs */
+ TABLE **net_table; /*!< points to 2d array of net attribs */
+ TABLE **pin_table; /*!< points to 2d array of pin attribs */
- int CHANGED; /* for "file not saved" warning upon exit */
+ int CHANGED; /*!< for "file not saved" warning upon exit */
};
-/* -------------------------------------------------------------------- *
+/* -------------------------------------------------------------------- */
+/* \brief Table cell struct
+ *
* st_table defined what is held in a spreadsheet cell for both
* comp and net spreadsheets. Holds pointer to individual comp/net name, and
* pointer to attrib list. Ideally, the name pointer points to the
* refdes/netname string held in the TOPLEVEL data structure, so that
* when SHEET_DATA is manipulated, so is TOPLEVEL.
- * -------------------------------------------------------------------- */
+ */
+/* -------------------------------------------------------------------- */
struct st_table {
- int row; /* location on spreadsheet */
- int col; /* location on spreadsheet */
- gchar *row_name; /* comp, net, or refdes:pin name */
- gchar *col_name; /* attrib name */
- gchar *attrib_value; /* attrib value */
+ int row; /*!< location on spreadsheet */
+ int col; /*!< location on spreadsheet */
+ gchar *row_name; /*!< comp, net, or refdes:pin name */
+ gchar *col_name; /*!< attrib name */
+ gchar *attrib_value; /*!< attrib value */
gint visibility;
gint show_name_value;
};
-/* -------------------------------------------------------------------- *
- * STRING_LIST is a list of strings. This struct is used for several
- * different jobs, including serving as base class for master lists.
- * -------------------------------------------------------------------- */
+/* -------------------------------------------------------------------- */
+/*! \brief A list of strings.
+ *
+ * STRING_LIST is a doubly-linked list of strings. This struct is
+ * used for several different jobs, including serving as base class
+ * for master lists.
+ *
+ * \todo Consider replacing with a GList-based implementation
+ */
+/* -------------------------------------------------------------------- */
struct st_string_list {
- gchar *data; /* holds string */
- int pos; /* pos on spreadsheet */
- int length; /* number of items in list */
- STRING_LIST *prev;
- STRING_LIST *next;
+ gchar *data; /*!< points to zero-terminated string */
+ int pos; /*!< position on spreadsheet */
+ int length; /*!< number of items in list */
+ STRING_LIST *prev; /*!< pointer to previous item in linked list */
+ STRING_LIST *next; /*!< pointer to next item in linked list */
};
-/* -------------------------------------------------------------------- *
+/* -------------------------------------------------------------------- */
+/*! \brief A list of pins
+ *
* PIN_LIST is a special struct used for keeping track of pins. Since
* the master_pin_list must keep track of both refdes and pin, we need a
* special struct for pins. Later processing will for a STRING_LIST
* of refdes:pinnumber pairs for insertion in the spreadsheet.
- * -------------------------------------------------------------------- */
+ *
+ * \todo Is this still in use? Consider replacing with a GList-based
+ * implementation.
+ */
+/* -------------------------------------------------------------------- */
struct st_pin_list {
- gchar *refdes; /* holds refdes string */
+ gchar *refdes; /*!< holds refdes string */
gint pinnumber;
- gchar *pinlabel; /* holds pin label string */
- int pos; /* pos on spreadsheet */
- int length; /* number of items in list */
+ gchar *pinlabel; /*!< holds pin label string */
+ int pos; /*!< pos on spreadsheet */
+ int length; /*!< number of items in list */
PIN_LIST *prev;
PIN_LIST *next;
};
-#endif
+#endif // #ifndef SHEET_DATA_STRUCT
diff --git a/gattrib/src/f_export.c b/gattrib/src/f_export.c
index 03d011a..c1245f7 100644
--- a/gattrib/src/f_export.c
+++ b/gattrib/src/f_export.c
@@ -17,9 +17,12 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns used for import/export of attrib sheets.
- *------------------------------------------------------------------*/
+/*! \file
+ * \brief Import/export functions
+ *
+ * This file holds fcns used for import/export of attribute sheets.
+ * At the moment, this is only component sheets.
+ */
#include <config.h>
@@ -44,11 +47,14 @@
/* =================== Public Functions ====================== */
/* ------------------------------------------------------------- */
-/* \brief This function is invoked when the user selects file ->
+/* \brief Export components to CSV
+ *
+ * This function is invoked when the user selects file ->
* export from the pull-down menu. It writes out a CSV file
* of the design for external processing.
*
- * ------------------------------------------------------------- */
+ * \param filename The name of the file to export to
+ */
void f_export_components(gchar *filename)
{
gint cur_page;
diff --git a/gattrib/src/g_rc.c b/gattrib/src/g_rc.c
index 7f2e158..dd3b0a1 100644
--- a/gattrib/src/g_rc.c
+++ b/gattrib/src/g_rc.c
@@ -16,6 +16,13 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*! \file
+ *
+ * \brief RC-file specific functions
+ *
+ * RC-file specific functions for Scheme. At the moment it only
+ * contains a function to test the version number of the program.
+ */
#include <config.h>
@@ -49,9 +56,12 @@
#include <dmalloc.h>
#endif
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*! \brief Test the version of gattrib and gEDA/gaf
*
- *------------------------------------------------------------------*/
+ * \param version Version being tested
+ * \returns false if incorrect version, true if OK
+ */
SCM g_rc_gattrib_version(SCM version)
{
SCM_ASSERT (scm_is_string (version), version,
diff --git a/gattrib/src/g_register.c b/gattrib/src/g_register.c
index aff0dc5..9662ada 100644
--- a/gattrib/src/g_register.c
+++ b/gattrib/src/g_register.c
@@ -16,6 +16,11 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*! \file
+ * \brief Functions to register Scheme functions
+ *
+ * Functions to register Scheme functions
+ */
#include <config.h>
@@ -48,11 +53,12 @@
/* ---------------------------------------------------------------------- */
-/*! \brief This function registers the Scheme functions required to use
+/*! \brief Register Scheme functions
+ *
+ * This function registers the Scheme functions required to use
* gattrib. They are mostly unnecessary, except for reading in the gattribrc
* file at the beginning of the prog which gives the library search paths.
- *
- * ---------------------------------------------------------------------- */
+ */
void g_register_funcs(void)
{
/* general functions */
@@ -64,6 +70,10 @@ void g_register_funcs(void)
}
+/*! \brief Scheme function to quit the application
+ *
+ * Quit the application from within Scheme.
+ */
SCM g_quit(void)
{
#ifdef DEBUG
diff --git a/gattrib/src/gattrib.c b/gattrib/src/gattrib.c
index 0e24500..2c2ac47 100644
--- a/gattrib/src/gattrib.c
+++ b/gattrib/src/gattrib.c
@@ -17,18 +17,87 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*****************************************************************************
- * In the spirit of open source/free software, major sections of *
- * gattrib's code were borrowed from other sources, and hacked *
- * together by SDB in Dec. 2003. Particularly rich sources for code were *
- * gEDA/gnetlist, and the gtkextra program testgtksheet.c. Thanks to their *
- * authors for providing the foundation upon which this is built. *
- * *
- * Of course, I *did* write major portions of the code too . . . . . *
- * Some documentation about the internal operation of this program can be *
- * found in the "NOTES" file in the gattrib top-level directory. *
- * -- SDB December 2003 - *
- *****************************************************************************/
+/**
+ * \mainpage
+ *
+ * \section sdb_notes SDB's original comment in gattrib.c
+ *
+ * In the spirit of open source/free software, major sections of
+ * gattrib's code were borrowed from other sources, and hacked
+ * together by SDB in Dec. 2003. Particularly rich sources for code were
+ * gEDA/gnetlist, and the gtkextra program testgtksheet.c. Thanks to their
+ * authors for providing the foundation upon which this is built.
+ *
+ * Of course, I *did* write major portions of the code too . . . . .
+ * Some documentation about the internal operation of this program can be
+ * found in the "NOTES" file in the gattrib top-level directory.
+ * -- SDB December 2003 -
+ *
+ * \section ml_notes Architecture
+ *
+ * (extracted from SDB's mailing list posting:
+ * http://osdir.com/ml/cad.geda.devel/2007-06/msg00282.html - believed to
+ * still be relevant)
+ *
+ * gattrib has three major components:
+ *
+ * -# It manipulates objects held in the TOPLEVEL data structure. It
+ * does this by importing structs and functions from libgeda.
+ * -# Gattrib defines its own layer of structs, notably SHEET_DATA,
+ * which holds a table of attrib name=value pairs, and also holds a
+ * couple of linked lists corresponding to all component's refdeses, and
+ * to all attribute names found in the design. This stuff is native to
+ * gattrib.
+ * -# Gattrib uses a spreadsheet widget called GtkSheet. This stuff
+ * came from the GtkExtra project, which at one time offered a bunch of
+ * interesting widgets for graphing and visualization. I think they're
+ * still around; you can do a Google search for them. I stole the two
+ * .h files defining the spreadsheet widgets, and also stole code from
+ * the program itself to implement the run-time functions which deal with
+ * the spreadsheet.
+ *
+ * When run, gattrib does this:
+ *
+ * -# It uses libgeda functions to read in your design, and fill up the
+ * TOPLEVEL struct.
+ * -# It then loops over everything in TOPLEVEL and fills out the refdes
+ * list and the attribute name list. It sticks these into a STRING_LIST
+ * which is associated with the SHEET_DATA struct.
+ * -# Then, knowing all the refdeses and all the attribute names, it
+ * creates a TABLE data struct (a member of SHEET_DATA), and loops over
+ * each cell in the TABLE. For each cell, it queries TOPLEVEL for the
+ * corresponding name=value pair, and sticks the value in the TABLE.
+ * -# When done with that, it then creates a GtkSheet and populates it
+ * by looping over TABLE.
+ * -# Then it turns over control to the user, who can manipulate the
+ * GtkSheet. As the user adds and deletes values from the GtkSheet, the
+ * values are stored locally there. The GtkSheet is the master
+ * repository of all attributes at that point; the other data structures
+ * are not updated.
+ *
+ * Saving out a design is similar, except the process runs in reverse:
+ *
+ * -# The program loops over all cells in GtkSheet, and sticks the
+ * values found into SHEET_DATA. Handling issues like added/deleted
+ * columns happens first at the GtkSheet, and then to SHEET_DATA and
+ * TOPLEVEL. I've kind of forgotten how I implemented these feaures,
+ * however. :-S
+ * -# Then, the program loops over the cells in SHEET_DATA, and updates
+ * the attributes in TOPLEVEL using functions from libgeda, as well as by
+ * reaching directly into the TOPLEVEL data structure (a software
+ * engineering no-no). If a previously existing attrib has been removed,
+ * then it is removed from TOPLEVEL. If a new attrib has been attached
+ * to a component, then it is added to TOPLEVEL.
+ * -# Then the design is saved out using the save function from
+ * libgeda.
+ *
+ * Therefore, think of SHEET_DATA and the other gattrib data structures
+ * as a thin layer between GtkSheet and TOPLEVEL. The gattrib data
+ * structures are used basically for convenience while trying to build or
+ * update either of the two other, more important data structures.
+ *
+ */
+
#include <config.h>
@@ -66,14 +135,16 @@
#endif
/*------------------------------------------------------------------*/
-/*! \brief gattrib_really_quit callback -- called when user
- * selects "quit" from menubar. Checks for unsaved
- * changes.
- * \par
- *
- * \return Returns 0 to shell (successful quit).
+/*! \brief GTK callback to quit the program.
*
- *------------------------------------------------------------------*/
+ * This is called when the user quits the program using the UI. The
+ * callback is attached to the GTK window_delete event in
+ * x_window_init() and attached to the File->Quit menu item in
+ * x_window_create_menu(). On execution, the function checks for
+ * unsaved changes before calling gattrib_quit() to quit the program.
+ *
+ * \return value 0 to the shell to denote a successful quit.
+ */
gboolean gattrib_really_quit(void)
{
if (sheet_head->CHANGED == TRUE) {
@@ -85,11 +156,14 @@ gboolean gattrib_really_quit(void)
}
/*------------------------------------------------------------------*/
-/*! \brief gattrib_quit -- wrap up and quit fcn.
+/*! \brief Quit the program.
*
- * \par
+ * Unconditionally quit gattrib. Flushes caches and I/O channels,
+ * calls the GTK function to quit the application then calls exit()
+ * with the appropriate return code.
*
- *------------------------------------------------------------------*/
+ * \param return_code Value to pass to the exit() system call.
+ */
gint gattrib_quit(gint return_code)
{
/* s_clib_cache_free(); */
@@ -106,11 +180,27 @@ gint gattrib_quit(gint return_code)
}
/*------------------------------------------------------------------*/
-/*! \brief gattrib_main -- main gattrib fcn.
+/*! \brief The "real" main for gattrib.
*
- * \par
+ * This is the main program body for gattrib. A pointer to this
+ * function is passed to scm_boot_guile() at startup.
*
- *------------------------------------------------------------------*/
+ * This function:
+ * - initialises threading, if the underlying GTK library is threaded.
+ * However, gattrib itself isn't threaded.
+ * - initialises libgeda;
+ * - parses the command line;
+ * - starts logging;
+ * - registers the Scheme functions with Guile;
+ * - parses the RC files;
+ * - initialises the GTK UI;
+ * - populates the spreadsheet data structure;
+ * - calls gtk_main() to start the event loop.
+ *
+ * \param closure
+ * \param argc Number of command line arguments
+ * \param argv Command line arguments
+ */
void gattrib_main(void *closure, int argc, char *argv[])
{
/* TOPLEVEL *pr_current is a global */
@@ -124,7 +214,8 @@ void gattrib_main(void *closure, int argc, char *argv[])
* backends uses threading so we need to call g_thread_init().
* GLib requires threading be initialised before any other GLib
* functions are called. Do it now if its not already setup. */
- if (!g_thread_supported ()) g_thread_init (NULL);
+ if (!g_thread_supported ())
+ g_thread_init (NULL);
#endif
/* Initialize gEDA stuff */
@@ -204,15 +295,17 @@ void gattrib_main(void *closure, int argc, char *argv[])
exit(0);
}
-/*------------------------------------------------------------------
- *! \brief main -- entry point to gattrib. This is just a wrapper which
- * invokes the guile stuff, and points to the real main prog,
- * gattrib_main. Note that I still need some vestigal
- * guile stuff in order to read the rc files.
+/*------------------------------------------------------------------*/
+/*! \brief Entry point to gattrib
*
- * \par
+ * This is just a wrapper which
+ * invokes the guile stuff, and points to the real main program,
+ * gattrib_main(). Note that I still need some vestigial
+ * guile stuff in order to read the rc files.
*
- *------------------------------------------------------------------*/
+ * \param argc Number of command line arguments
+ * \param argv Command line arguments
+ */
int main(int argc, char *argv[])
{
/* This is i18n stuff */
@@ -228,6 +321,9 @@ int main(int argc, char *argv[])
if(getenv("GUILE_WARN_DEPRECATED")==NULL)
putenv("GUILE_WARN_DEPRECATED=no");
+ /* Initialize the Guile Scheme interpreter. This function does not
+ * return but calls exit(0) on completion.
+ */
scm_boot_guile( argc, argv, gattrib_main, NULL);
exit(0); /* This is not real exit point. Real exit is in gattrib_quit. */
diff --git a/gattrib/src/globals.c b/gattrib/src/globals.c
index 9a8185c..65d497c 100644
--- a/gattrib/src/globals.c
+++ b/gattrib/src/globals.c
@@ -17,6 +17,12 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*! \file
+ * \brief Global declarations
+ *
+ * Global declarations
+ */
+
#include <config.h>
#include <stdio.h>
@@ -33,11 +39,13 @@
#endif
/* command line arguments */
-int verbose_mode=FALSE;
-int quiet_mode=FALSE;
+int verbose_mode=FALSE; //!< Reflects the value of the command line flag
+int quiet_mode=FALSE; //!< Reflects the value of the command line flag
-/* these are required by libgeda */
-/* I have made most of these NULL because they aren't needed
- * for gattrib -- no drawing is done. */
+/*!
+ * these are required by libgeda
+ * I have made most of these NULL because they aren't needed
+ * for gattrib -- no drawing is done.
+ */
void (*variable_set_func)() = i_vars_set;
diff --git a/gattrib/src/i_basic.c b/gattrib/src/i_basic.c
index a3787a4..513b5ad 100644
--- a/gattrib/src/i_basic.c
+++ b/gattrib/src/i_basic.c
@@ -18,7 +18,11 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-
+/*! \file
+ *
+ * \todo Unused function in here, i_update_status(). File is a candidate
+ * for removal?
+ */
#include <config.h>
diff --git a/gattrib/src/i_vars.c b/gattrib/src/i_vars.c
index 4b4573d..02eb49b 100644
--- a/gattrib/src/i_vars.c
+++ b/gattrib/src/i_vars.c
@@ -17,6 +17,12 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*! \file
+ * \brief Functions for variable setting.
+ *
+ * Functions for variable setting.
+ */
+
#include <config.h>
#include <stdio.h>
@@ -43,16 +49,23 @@
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*
* Define the vars we'll use later
*------------------------------------------------------------------*/
-int default_paper_width = 11000; /* letter size */
-int default_paper_height = 85000;
+int default_paper_width = 11000; /*!< width for letter paper (landscape)
+ * \todo Can this be const? */
+int default_paper_height = 85000;/*!< height for letter paper (landscape)
+ * \todo Can this be const? */
-/*------------------------------------------------------------------
- * This initializes the vars in pr_current.
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*! \brief Initialise variables in pr_current
+ *
+ * Initialize the variables in pr_current. In practice, this is only
+ * the paper size for the sheet.
+ * \param pr_current pointer to the TOPLEVEL to set paper size in.
+ */
void i_vars_set(TOPLEVEL * pr_current)
{
i_vars_libgeda_set(pr_current);
diff --git a/gattrib/src/listsort.c b/gattrib/src/listsort.c
index d5948f9..8e7dfa6 100644
--- a/gattrib/src/listsort.c
+++ b/gattrib/src/listsort.c
@@ -1,9 +1,11 @@
/*----------------------------------------------------------------*
+/*! \file
* Linked list sorting code taken from
* http://www.chiark.greenend.org.uk/~sgtatham/algorithms/listsort.html
* and hacked to serve in gattrib by SDB.
- *----------------------------------------------------------------*/
+ *
+ */
/*
* Demonstration code for sorting a linked list.
@@ -73,9 +75,15 @@
#endif
-/*----------------------------------------------------------------*
+/*----------------------------------------------------------------*/
+/*! \brief Compare values of string data
+ *
* Comparison function -- compare values of string data.
- *----------------------------------------------------------------*/
+ * \param al pointer to first STRING_LIST item to be compared
+ * \param bl pointer to second STRING_LIST item to be compared
+ * \returns +ve if al > bl, -ve if al < bl, 0 if al = bl
+ */
+/*----------------------------------------------------------------*/
int cmp(STRING_LIST *al, STRING_LIST *bl) {
char *a = al->data;
char *b = bl->data;
@@ -108,18 +116,26 @@ int cmp(STRING_LIST *al, STRING_LIST *bl) {
return 0;
}
-/*----------------------------------------------------------------*
+/*----------------------------------------------------------------*/
+/*! \brief Sort the linked list
+ *
* This is the actual sort function. Notice that it returns the new
* head of the list. (It has to, because the head will not
* generally be the same element after the sort.) So unlike sorting
* an array, where you can do
*
- * sort(myarray);
+ * - sort(myarray);
*
* you now have to do
*
- * list = listsort(mylist);
- *----------------------------------------------------------------*/
+ * - list = listsort(mylist);
+ *
+ * \param list The linked STRING_LIST to be sorted
+ * \param is_circular TRUE if this is a circularly linked list
+ * \param is_double TRUE if this is a doubly-linked list
+ * \returns a pointer to the new head of the list
+ */
+/*----------------------------------------------------------------*/
STRING_LIST *listsort(STRING_LIST *list, int is_circular, int is_double) {
STRING_LIST *p, *q, *e, *tail, *oldhead;
int insize, nmerges, psize, qsize, i;
diff --git a/gattrib/src/parsecmd.c b/gattrib/src/parsecmd.c
index 015435e..352a1d7 100644
--- a/gattrib/src/parsecmd.c
+++ b/gattrib/src/parsecmd.c
@@ -16,6 +16,13 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*!
+ * \file
+ * \brief Functions to parse the command line.
+ *
+ * Functions to parse the command line and to provide usage
+ * information.
+ */
#include <config.h>
@@ -33,6 +40,11 @@
#endif /* Checking for getopt */
#if !defined(HAVE_GETOPT_LONG) || !defined(HAVE_GETOPT_H)
+/*! \brief Command line option string for getopt.
+ *
+ * Command line option string for getopt. Defines "q" for quiet,
+ * "v" for verbose and "h" for help.
+ */
#define OPTIONS "qvh"
#ifndef OPTARG_IN_UNISTD
extern char *optarg;
@@ -54,6 +66,13 @@ extern int optind;
#include "../include/prototype.h" /* function prototypes */
#include "../include/globals.h"
+/*!
+ * \brief Print usage message
+ *
+ * Prints gattrib usage information to stdout.
+ * \param cmd Unused parameter.
+ *
+ */
void usage(char *cmd)
{
@@ -84,7 +103,19 @@ void usage(char *cmd)
exit(0);
}
-
+/*!
+ * \brief Parse command line switches.
+ *
+ * Parse command line switches at startup. There are only 3 command
+ * line switches:
+ * - verbose
+ * - quiet
+ * - help
+ * \param argc Number of command line arguments
+ * \param argv Command line arguments (array of strings)
+ * \returns I don't know what - looks uninitialised in some circumstances.
+ *
+ */
int parse_commandline(int argc, char *argv[])
{
int ch;
diff --git a/gattrib/src/s_attrib.c b/gattrib/src/s_attrib.c
index 5f69e9c..615bde8 100644
--- a/gattrib/src/s_attrib.c
+++ b/gattrib/src/s_attrib.c
@@ -17,6 +17,14 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*!
+ * \file
+ * \brief Functions to operate on attributes in STRING_LISTs
+ *
+ * Various functions to operate on attribute name=value pairs in supplied
+ * STRING_LIST structs.
+ */
+
#include <config.h>
#include <stdio.h>
@@ -39,12 +47,15 @@
/*------------------------------------------------------------------*/
-/*! \brief This fcn is passed a STRING_LIST of name=value pairs, and a
- * name.
+/*! \brief Detect "name" in STRING_LIST
*
- * \return It returns 1 (TRUE) if the name is in the STRING_LIST, otherwise
- * it returns 0 (FALSE).
- *------------------------------------------------------------------*/
+ * This function is passed a STRING_LIST of name=value pairs, and a
+ * name.
+ * \param name_value_list pointer to STRING_LIST to search
+ * \param name name string to search for
+ * \returns 1 (TRUE) if the name is in the STRING_LIST, otherwise
+ * it returns 0 (FALSE).
+ */
int s_attrib_name_in_list(STRING_LIST *name_value_list, char *name)
{
STRING_LIST *local_list_item;
@@ -69,13 +80,15 @@ int s_attrib_name_in_list(STRING_LIST *name_value_list, char *name)
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes an object, finds its refdes and returns it.
+/*! \brief Locate the refdes associated with an object.
*
- * \return For normal components, it returns a (pointer to a)
- * string containing the
- * refdes If the component is slotted, it returns a refdes of the form
- * refdes.slot. If no refdes is found, it returns NULL.
- *------------------------------------------------------------------*/
+ * This fcn takes an object, finds its refdes and returns it.
+ * \param object Pointer to the object to search for.
+ * \return For normal components, it returns a pointer to a
+ * string containing the refdes. If the component is slotted,
+ * it returns a refdes of the form
+ * refdes.slot. If no refdes is found, it returns NULL.
+ */
char *s_attrib_get_refdes(OBJECT *object)
{
char *temp_uref;
diff --git a/gattrib/src/s_misc.c b/gattrib/src/s_misc.c
index cfa2fe3..9259041 100644
--- a/gattrib/src/s_misc.c
+++ b/gattrib/src/s_misc.c
@@ -17,6 +17,10 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*! \file
+ * \brief Miscellaneous STRING_LIST functions
+ */
+
#include <config.h>
#include <stdio.h>
@@ -42,8 +46,18 @@
* The below fcns identical to those defined in
* geda-gnetlist/src/s_misc.c
*------------------------------------------------------------------*/
+/*!
+ * Running count of number of characters printed on current line.
+ */
static int char_index = 0;
+/*! \brief Print message in verbose mode
+ *
+ * Print the supplied message in verbose mode. Line wrap if necessary.
+ *
+ * Identical to that defined in gnetlist/src/s_misc.c
+ * \param string String to be printed
+ */
void verbose_print(char *string)
{
if (verbose_mode) {
@@ -56,6 +70,13 @@ void verbose_print(char *string)
}
}
+/*! \brief Print "DONE" message in verbose mode
+ *
+ * Prints the "DONE" message in verbose mode, wrapping before printing
+ * if near the end of line.
+ *
+ * Identical to function defined in gnetlist/src/s_misc.c
+ */
void verbose_done(void)
{
if (verbose_mode) {
@@ -69,6 +90,13 @@ void verbose_done(void)
}
}
+/*! \brief Reset the running character count
+ *
+ * Reset the current characted count.
+ *
+ * Identical to function defined in gnetlist/src/s_misc.c
+ */
+
void verbose_reset_index(void)
{
char_index = 0;
@@ -78,7 +106,6 @@ void verbose_reset_index(void)
/*------------------------------------------------------------------
* Gattrib specific utilities
*------------------------------------------------------------------*/
-
char *s_misc_remaining_string(gchar *string, gchar delimiter, gint count)
{
gint i;
diff --git a/gattrib/src/s_object.c b/gattrib/src/s_object.c
index 8c84995..db9ccd2 100644
--- a/gattrib/src/s_object.c
+++ b/gattrib/src/s_object.c
@@ -17,15 +17,18 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns involved in manipulating the OBJECT data
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions for manipulating OBJECTs.
+ *
+ * This file holds functions involved in manipulating the OBJECT data
* structure. OBJECT is defined in libgeda. An OBJECT is a graphical
* primitive normally used in gschem. Example OBJECTs: some text,
* a component (complex), a pin, a line, etc.
*
- * The fcns herein are fcns which I wrote as wrappers to the
+ * The functions herein are functions which I wrote as wrappers to the
* fcns in libgeda.
- *------------------------------------------------------------------ */
+ */
#include <config.h>
@@ -57,16 +60,22 @@
/* =================== Public Functions ====================== */
/*------------------------------------------------------------------*/
-/*! \brief This fcn adds a new attrib to o_current, when o_current is a
+/*! \brief Add an attribute to an OBJECT
+ *
+ * This fcn adds a new attrib to o_current, when o_current is a
* component. It does it in the following
* way:
- * 1. It creates an object -- "attrib_graphic" -- and fills it in.
- * 2. It gets the position info from o_current's refdes attrib and
- * calls o_text_new to add pos info and name=value string
+ * -# It creates an object -- "attrib_graphic" -- and fills it in.
+ * -# It gets the position info from o_current's refdes attrib and
+ * calls o_text_new() to add position info and name=value string
* to attrib_graphic.
- * 3. It calls o_attrib_add to wrap attrib_graphic with (attribute OBJECT )
- *
- *------------------------------------------------------------------ */
+ * -# It calls o_attrib_add() to wrap attrib_graphic with (attribute OBJECT )
+ * \param o_current pointer to object to add attribute to
+ * \param new_attrib_name name of the attribute to add
+ * \param new_attrib_value value of the attribute to add
+ * \param visibility Is the attribute visible?
+ * \param show_name_value Control visibility of name and value.
+ */
void s_object_add_comp_attrib_to_object(OBJECT *o_current,
char *new_attrib_name,
char *new_attrib_value,
@@ -90,9 +99,9 @@ void s_object_add_comp_attrib_to_object(OBJECT *o_current,
/*------------------------------------------------------------------*/
-/*! /brief This needs to be filled in.
- *
- *------------------------------------------------------------------*/
+/*!
+ * \todo This needs to be filled in.
+ */
void s_object_add_net_attrib_to_object(OBJECT *o_current, char *new_attrib_name,
char *new_attrib_value)
{
@@ -101,18 +110,22 @@ void s_object_add_net_attrib_to_object(OBJECT *o_current, char *new_attrib_name,
/*------------------------------------------------------------------*/
-/*! \brief This fcn adds a new attrib to o_current, when o_current is a
+/*! \brief Add a new attribute to an pin OBJECT
+ *
+ * Add a new attribute to o_current, when o_current is a
* pin. It does it in the following
* way:
- * 1. It creates an object -- "attrib_graphic" -- and fills it in.
- * 2. It gets the position info from o_current's refdes attrib and
- * calls o_text_new to add pos info and name=value string
+ * -# It creates an object -- "attrib_graphic" -- and fills it in.
+ * -# It gets the position info from o_current's refdes attrib and
+ * calls o_text_new() to add position info and name=value string
* to attrib_graphic.
- * 3. It calls o_attrib_add to wrap attrib_graphic with (attribute OBJECT )
- * Question: Do I really need separate fcns for comps, nets, and
+ * -# It calls o_attrib_add() to wrap attrib_graphic with (attribute OBJECT )
+ * \param o_current Pointer to pin object
+ * \param new_attrib_name Name of attribute to add
+ * \parma new_attrib_value Value of attribute to add
+ * \todo Do I really need separate fcns for comps, nets, and
* pins???
- *
- *------------------------------------------------------------------ */
+ */
void s_object_add_pin_attrib_to_object(OBJECT *o_current, char *new_attrib_name,
char *new_attrib_value)
{
@@ -133,13 +146,17 @@ void s_object_add_pin_attrib_to_object(OBJECT *o_current, char *new_attrib_name,
}
-
-
/*------------------------------------------------------------------*/
-/*! \brief This fcn finds the instance of attrib_name on o_current, and
- * replaces it's value wiht new_attrib_value.
+/*! \brief Replace attribute value in object
*
- *------------------------------------------------------------------*/
+ * Find the instance of attrib_name on o_current, and
+ * replace its value with the new_attrib_value.
+ * \param o_current object to operate on
+ * \param new_attrib_name name of attribute to replace
+ * \param new_attrib_value value to set attribute to
+ * \param visibility set visibility of attribute
+ * \param show_name_value set visibility of attribute name and value
+ */
void s_object_replace_attrib_in_object(OBJECT *o_current,
char *new_attrib_name,
char *new_attrib_value,
@@ -195,9 +212,13 @@ void s_object_replace_attrib_in_object(OBJECT *o_current,
/*------------------------------------------------------------------*/
-/*! \brief This fcn removes attrib from o_current.
+/*!
+ * \brief Remove attribute from object
*
- *------------------------------------------------------------------*/
+ * Remove an attribute from an object.
+ * \param o_current Object to remove attribute from
+ * \param new_attrib_name Name of attribute to remove
+ */
void s_object_remove_attrib_in_object(OBJECT *o_current, char *new_attrib_name)
{
GList *a_iter;
@@ -247,11 +268,19 @@ void s_object_remove_attrib_in_object(OBJECT *o_current, char *new_attrib_name)
/*------------------------------------------------------------------*/
-/*! \brief This fcn attaches the name=value pair to the OBJECT "object" It
- * was stolen from gschem/src/o_attrib.c:o_attrib_add_attrib and
- * hacked for gattrib. Does it need to return OBJECT?
+/*! \brief Attach attribute to object.
*
- *------------------------------------------------------------------*/
+ * Attach the name=value pair to the OBJECT "object". This function
+ * was stolen from gschem/src/o_attrib.c:o_attrib_add_attrib and
+ * hacked for gattrib.
+ * \param pr_current TOPLEVEL to operate on
+ * \param text_string
+ * \param visibility
+ * \param show_name_value
+ * \param object
+ * \returns pointer to the object
+ * \todo Does it need to return OBJECT?
+ */
OBJECT *s_object_attrib_add_attrib_in_object(TOPLEVEL * pr_current, char *text_string,
int visibility, int show_name_value,
OBJECT * object)
@@ -336,10 +365,14 @@ OBJECT *s_object_attrib_add_attrib_in_object(TOPLEVEL * pr_current, char *text_s
/*------------------------------------------------------------------*/
-/*! \brief This fcn deletes the text object pointed to by text_object. It
+/*! \brief Delete text object
+ *
+ * Delete the text object pointed to by text_object. This function
* was shamelessly stolen from gschem/src/o_delete.c and hacked
* for gattrib by SDB.
- *------------------------------------------------------------------*/
+ * \param pr_current TOPLEVEL to be operated on
+ * \param test_object text object to be deleted
+ */
void s_object_delete_text_object_in_object(TOPLEVEL * pr_current, OBJECT * text_object)
{
s_page_remove (pr_current, pr_current->page_current, text_object);
@@ -349,11 +382,12 @@ void s_object_delete_text_object_in_object(TOPLEVEL * pr_current, OBJECT * text_
/*------------------------------------------------------------------*/
-/*! \brief This verifies that the object has a non-null symbol file.
+/*! \brief Ensure object has a symbol file
*
- * \returns It returns 0 = valid symbol file, 1 = no symbol file found.
+ * This verifies that the object has a non-null symbol file.
*
- *------------------------------------------------------------------*/
+ * \returns 0 = valid symbol file, 1 = no symbol file found.
+ */
int s_object_has_sym_file(OBJECT *object)
{
char *filename;
diff --git a/gattrib/src/s_rename.c b/gattrib/src/s_rename.c
index a5b5dc8..868b046 100644
--- a/gattrib/src/s_rename.c
+++ b/gattrib/src/s_rename.c
@@ -17,6 +17,12 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*!
+ * \file
+ * \brief Functions to rename STRING_LIST contents
+ *
+ * Functions to rename STRING_LIST contents
+ */
#include <config.h>
#include <stdio.h>
@@ -53,12 +59,19 @@ typedef struct {
#define MAX_RENAME 64
#define MAX_SETS 10
-/* size is fixed... TODO: maybe make this dynamic */
+/*! size is fixed...
+ * \todo maybe make this dynamic */
static RENAME rename_pairs[MAX_SETS][MAX_RENAME];
static int rename_counter = 0;
static int cur_set = 0;
+
+/*! \brief Initialize the renaming data space
+ *
+ * Initialise the renaming data space by setting all the pair pointers
+ * to NULL.
+ */
void s_rename_init(void)
{
int i, j;
@@ -73,6 +86,11 @@ void s_rename_init(void)
cur_set = 0;
}
+/*! \brief Free all data referred to by the rename pairs
+ *
+ * Runs through the rename pairs and calls g_free() on the non-NULL
+ * entries, then sets the entry to NULL.
+ */
void s_rename_destroy_all(void)
{
int i, j;
@@ -106,6 +124,10 @@ void s_rename_next_set(void)
rename_counter = 0;
}
+/*! \brief Print all rename sets
+ *
+ * Iterate through the array and print all the rename sets to stdout.
+ */
void s_rename_print(void)
{
int i,j;
@@ -123,9 +145,17 @@ void s_rename_print(void)
}
}
-/* if the src is found, return true */
-/* if the dest is found, also return true, but warn user */
-/* If quiet_flag is true than don't print anything */
+/*! \brief Search the rename sets
+ *
+ * Search through the rename sets looking for src and dest. If
+ * quiet_flag is true than don't print anything.
+ * \param src Source to search for
+ * \param dest Destination to search for
+ * \param quiet_flag Suppress printing if set to TRUE
+ * \returns TRUE if the
+ * src is found. If the dest is found, also return true, but warn
+ * user
+ */
int s_rename_search(char *src, char *dest, int quiet_flag)
{
int i;
@@ -154,6 +184,13 @@ int s_rename_search(char *src, char *dest, int quiet_flag)
return (FALSE);
}
+/*! \brief Add to the rename pairs
+ *
+ * Add a source and destination to the rename pairs.
+ * \param src Source to add
+ * \param dest Destination to add
+ */
+
void s_rename_add(char *src, char *dest)
{
int flag;
@@ -206,6 +243,8 @@ void s_rename_add(char *src, char *dest)
}
+
+
void s_rename_all_lowlevel(NETLIST * netlist_head, char *src, char *dest)
{
NETLIST *nl_current = NULL;
diff --git a/gattrib/src/s_sheet_data.c b/gattrib/src/s_sheet_data.c
index 3f8996d..4154bf5 100644
--- a/gattrib/src/s_sheet_data.c
+++ b/gattrib/src/s_sheet_data.c
@@ -17,13 +17,19 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns involved in manipulating an entire SHEET_DATA
- * structure. The SHEET_DATA structure is the intermediate structure
- * between TOPLEVEL (gEDA's native format) and the graphical gtksheet
- * widget (from gtkextra), which is the spreadsheet widget displaying
- * the attribs.
- *------------------------------------------------------------------*/
+/*--------------------------------------------------------------*/
+/*!
+ * \file
+ *
+ * \brief Functions involved in manipulating an entire
+ * SHEET_DATA structure.
+ *
+ * This file holds functions involved in manipulating an entire
+ * SHEET_DATA structure. The SHEET_DATA structure is the intermediate
+ * structure between TOPLEVEL (gEDA's native format) and the graphical
+ * gtksheet widget (from gtkextra), which is the spreadsheet widget
+ * displaying the attribs.
+ */
#include <config.h>
@@ -47,11 +53,12 @@
/*------------------------------------------------------------------*/
-/*! \brief This fcn is the sheet_data creator.
- * It returns a pointer to
- * an initialized SHEET_DATA struct.
+/*!
+ * \brief Create a SHEET_DATA struct.
*
- *------------------------------------------------------------------*/
+ * Creates an initialised but empty SHEET_DATA struct.
+ * \returns a pointer to a SHEET_DATA struct.
+ */
SHEET_DATA *s_sheet_data_new()
{
SHEET_DATA *new_sheet;
@@ -92,14 +99,14 @@ SHEET_DATA *s_sheet_data_new()
/*------------------------------------------------------------------*/
-/*! \brief This fcn adds to the master list of
- * components refdeses by running
- * through the components and recording the comp refdeses
- * it discovers. Then it sorts them into alphabetical order.
- * Data struct being searched is:
- * OBJECT->attribs(->next. . .)->object->text->string
- *
- *------------------------------------------------------------------*/
+/*! \brief Add components to master list
+ *
+ * Add to the master list of components refdeses by running through
+ * the components and recording the comp refdeses it discovers. Then
+ * it sorts them into alphabetical order. Data struct being searched
+ * is: OBJECT->attribs(->next. . .)->object->text->string
+ * \param obj_list pointer to the component list to be added.
+ */
void s_sheet_data_add_master_comp_list_items (const GList *obj_list) {
char *temp_uref;
const GList *iter;
@@ -153,14 +160,16 @@ void s_sheet_data_add_master_comp_list_items (const GList *obj_list) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn adds to the master list of comp attribs by running
+/*! \brief Add attributes to master list
+ *
+ * Add to the master list of comp attributes by running
* through each component on the page and recording all attribs
* it discovers. Then it sorts them into an order used for the
* horiz listing of the attribs on the spreadsheet.
* Data struct being searched is:
* sheet_head->component_list_head->attrib->name;
- *
- *------------------------------------------------------------------*/
+ * \param obj_list pointer to list of attributes being added
+ */
void s_sheet_data_add_master_comp_attrib_list_items (const GList *obj_list) {
char *attrib_text;
char *attrib_name;
@@ -230,46 +239,50 @@ void s_sheet_data_add_master_comp_attrib_list_items (const GList *obj_list) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn builds the master list of net names by running
+/*! \brief Add net names to master list.
+ *
+ * Build the master list of net names by running
* through the individual cells and recording the net refdeses
* it discovers.
* It's currently empty, waiting for implementation of net
* attributes.
- *
- *------------------------------------------------------------------*/
+ */
void s_sheet_data_add_master_net_list_items (const GList *obj_start) {
return;
}
/*------------------------------------------------------------------*/
-/*! \brief This fcn builds the master list of net attribs.
+/*! \brief Add net attributes to master list.
+ *
+ * Build the master list of net attribs.
* It's currently empty, waiting for implementation of net
* attributes.
- *
- *------------------------------------------------------------------*/
+ */
void s_sheet_data_add_master_net_attrib_list_items (const GList *obj_start) {
return;
}
/*------------------------------------------------------------------*/
-/*! \brief This fcn builds the master
+/*! \brief Add pin names to master list.
+ *
+ * Build the master
* list of pin names. It writes the
* label refdes:pinnumber into the global master pin list.
* Algorithm:
- * 1. Loop on o_current looking for OBJ_COMPLEX
- * 2. When we find a complex, save the refdes.
- * 3. Dive down to o_lower_current = o_current->complex->prim_objs
- * 4. Loop on o_lower_current looking for OBJ_PIN
- * 5. When we find a pin, find the pinnumber by calling
- * o_attrib_search_object_attribs_by_name (o_lower_current, "pinnumber", 0)
- * 6. Create the pin list label as "refdes=XXX", and stick it into
- * the master pin list.
- * Since this fcn operates on the global sheet_data->master_pin_list,
+ * -# Loop on o_current looking for OBJ_COMPLEX
+ * -# When we find a complex, save the refdes.
+ * -# Dive down to o_lower_current = o_current->complex->prim_objs
+ * -# Loop on o_lower_current looking for OBJ_PIN
+ * -# When we find a pin, find the pinnumber by calling
+ * o_attrib_search_object_attribs_by_name(o_lower_current, "pinnumber", 0)
+ * -# Create the pin list label as "refdes=XXX", and stick it into
+ * the master pin list.
+ * Since this function operates on the global sheet_data->master_pin_list,
* it doesn't return a value.
- *
- *------------------------------------------------------------------*/
+ * \param obj_list pointer to list of pin names to be added.
+ */
void s_sheet_data_add_master_pin_list_items (const GList *obj_list) {
char *temp_uref;
char *temp_pinnumber;
@@ -344,20 +357,22 @@ void s_sheet_data_add_master_pin_list_items (const GList *obj_list) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn builds the master
+/*! \brief Add pin attributes to master list.
+ *
+ * Build the master
* list of pin attributes. It writes
* each attrib name into the master pin attrib list.
* Algorithm:
- * 1. Loop on o_current looking for OBJ_COMPLEX
- * 2. When we find a complex, save the refdes.
- * 3. Dive down to o_lower_current = o_current->complex->prim_objs
- * 4. Loop on o_lower_current looking for OBJ_PIN
- * 5. When we find a pin, get pin_attribs = o_lower_current->attribs
- * 6. Loop on attribs looking for non-NULL text.
- * 7. When we find a non-NULL text attrib, extract the attrib name
- * and stick it in the master pin attrib list.
- *
- *------------------------------------------------------------------*/
+ * -# Loop on o_current looking for OBJ_COMPLEX
+ * -# When we find a complex, save the refdes.
+ * -# Dive down to o_lower_current = o_current->complex->prim_objs
+ * -# Loop on o_lower_current looking for OBJ_PIN
+ * -# When we find a pin, get pin_attribs = o_lower_current->attribs
+ * -# Loop on attribs looking for non-NULL text.
+ * -# When we find a non-NULL text attrib, extract the attrib name
+ * and stick it in the master pin attrib list.
+ * \param obj_list pointer to list of pin attributes to be added.
+ */
void s_sheet_data_add_master_pin_attrib_list_items (const GList *obj_list) {
char *temp_uref;
char *attrib_text;
@@ -442,12 +457,14 @@ void s_sheet_data_add_master_pin_attrib_list_items (const GList *obj_list) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn extracts the attribs from the gtksheet
+/*!
+ * \brief Extract data from gtksheet
+ *
+ * This fcn extracts the attribs from the gtksheet widget
* cells, and places them back into SHEET_DATA. This is the
* first step in saving out a project. Right now I just invoke
* s_table_gtksheet_to_table. Do I need to do anything else here?
- *
- *------------------------------------------------------------------*/
+ */
void s_sheet_data_gtksheet_to_sheetdata() {
s_table_gtksheet_to_all_tables();
/* do I need to do anything else here? */
diff --git a/gattrib/src/s_string_list.c b/gattrib/src/s_string_list.c
index d5e4760..b56dc6f 100644
--- a/gattrib/src/s_string_list.c
+++ b/gattrib/src/s_string_list.c
@@ -17,11 +17,21 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns involved in manipulating the STRING_LIST
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions involved in manipulating the STRING_LIST
+ * structure.
+ *
+ * This file holds functions involved in manipulating the STRING_LIST
* structure. STRING_LIST is basically a linked list of strings
* (text).
- *------------------------------------------------------------------*/
+ *
+ * \todo This could be implemented using an underlying GList
+ * structure. The count parameter could also be eliminated -
+ * either store it in the struct or preferably, calculate it
+ * when needed - I don't think the speed penalty of traversing
+ * the list is significant at all. GDE
+ */
#include <config.h>
@@ -46,9 +56,11 @@
/*------------------------------------------------------------------*/
-/*! \brief This returns a pointer to a new STRING_LIST object.
+/*! \brief Return a pointer to a new STRING_LIST
*
- *------------------------------------------------------------------*/
+ * Returns a pointer to a new STRING_LIST struct. This list is empty.
+ * \returns pointer to the new STRING_LIST struct.
+ */
STRING_LIST *s_string_list_new() {
STRING_LIST *local_string_list;
@@ -63,10 +75,13 @@ STRING_LIST *s_string_list_new() {
/*------------------------------------------------------------------*/
-/*! \brief This takes an old string list, duplicates it and returns a pointer
- * to the new, duplicate list.
+/*! \brief Duplicate a STRING_LIST
*
- *------------------------------------------------------------------*/
+ * Given a STRING_LIST, duplicate it and returns a pointer
+ * to the new, duplicate list.
+ * \param old_string_list pointer to the STRING_LIST to be duplicated
+ * \returns a pointer to the duplicate STRING_LIST
+ */
STRING_LIST *s_string_list_duplicate_string_list(STRING_LIST *old_string_list) {
STRING_LIST *new_string_list;
STRING_LIST *local_string_list;
@@ -92,19 +107,15 @@ STRING_LIST *s_string_list_duplicate_string_list(STRING_LIST *old_string_list) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn inserts the item into a char* list.
- * It first cycles through the
- * list to make sure that there are no duplications. The list is assumed
- * to be a STRING_LIST:
- * struct STRING_LIST
- * {
- * char *data;
- * int pos;
- * STRING_LIST *next;
- * STRING_LIST *prev;
- * };
+/*! \brief Add an item to a STRING_LIST
*
- *------------------------------------------------------------------*/
+ * Inserts the item into a STRING_LIST.
+ * It first passes through the
+ * list to make sure that there are no duplications.
+ * \param list pointer to STRING_LIST to be added to.
+ * \param count FIXME Don't know what this does - input or output? both?
+ * \param item pointer to string to be added
+ */
void s_string_list_add_item(STRING_LIST *list, int *count, char *item) {
gchar *trial_item = NULL;
@@ -161,11 +172,13 @@ void s_string_list_add_item(STRING_LIST *list, int *count, char *item) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn deletes an item in a STRING_LIST.
- * It takes args: list to to delete item, pointer to no of items in
- * list at end, and the item itself to remove.
+/*! \brief Delete an item from a STRING_LIST
*
- *------------------------------------------------------------------*/
+ * Deletes an item in a STRING_LIST.
+ * \param list pointer to STRING_LIST
+ * \param count pointer to count of items in list
+ * \param item item to remove from list
+ */
void s_string_list_delete_item(STRING_LIST **list, int *count, gchar *item) {
gchar *trial_item = NULL;
@@ -244,12 +257,15 @@ void s_string_list_delete_item(STRING_LIST **list, int *count, gchar *item) {
}
-
/*------------------------------------------------------------------*/
-/*! \brief This fcn looks for item in the list. It returns 1 if item is
- * present, 0 if absent.
+/*! \brief Detect item in list
*
- *------------------------------------------------------------------*/
+ * Look for item in the list.
+ *
+ * \param list pointer to the STRING_LIST struct
+ * \param item string to search for
+ * \returns 0 if absent, 1 if present
+ */
int s_string_list_in_list(STRING_LIST *list, char *item) {
gchar *trial_item = NULL;
@@ -281,10 +297,14 @@ int s_string_list_in_list(STRING_LIST *list, char *item) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn returns the index'th item in the string list.
- * It returns NULL if there is a problem
+/*! \brief Get an item from a STRING_LIST by index
*
- *------------------------------------------------------------------*/
+ * Returns the index'th item in the string list.
+ * \param list pointer to STRING_LIST to get from
+ * \param index index of item to return
+ * \returns NULL if there is a problem otherwise a pointer to
+ * the string.
+ */
gchar *s_string_list_get_data_at_index(STRING_LIST *list, gint index)
{
gint i;
@@ -309,14 +329,15 @@ gchar *s_string_list_get_data_at_index(STRING_LIST *list, gint index)
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes the master comp list
+/*! \brief Sort the master component list
+ *
+ * Takes the master comp list
* sheet_head->master_comp_list_head
* and sorts it in this order:
* <all refdeses in alphabetical order>
* Right now it does nothing other than fill in the "position"
* and "length" variables.
- *
- *------------------------------------------------------------------*/
+ */
void s_string_list_sort_master_comp_list() {
int i = 0;
STRING_LIST *local_list, *p;
@@ -349,15 +370,6 @@ void s_string_list_sort_master_comp_list() {
return;
}
-/*------------------------------------------------------------------*/
-/*! \brief This fcn takes the master comp attrib list
- * sheet_head->master_comp_attrib_list_head
- * and sorts it in this order:
- * <all refdeses in alphabetical order>
- * Right now it does nothing other than fill in the "position"
- * and "length" variables.
- *
- *------------------------------------------------------------------*/
/* This list overrides the alphanumeric sort. Attribs not found in
this list are sorted as if they had a value of DEFAULT_ATTRIB_POS
@@ -374,6 +386,16 @@ static struct {
#define NUM_CERTAINS (sizeof(certain_attribs)/sizeof(certain_attribs[0]))
#define DEFAULT_ATTRIB_POS 100
+/*------------------------------------------------------------------*/
+/*! \brief Sort the master component attribute list
+ *
+ * Take the master comp attrib list
+ * sheet_head->master_comp_attrib_list_head
+ * and sort it in this order:
+ * <all refdeses in alphabetical order>
+ * Right now it does nothing other than fill in the "position"
+ * and "length" variables.
+ */
void s_string_list_sort_master_comp_attrib_list() {
int i = 0;
STRING_LIST *local_list, *p;
@@ -413,12 +435,13 @@ void s_string_list_sort_master_comp_attrib_list() {
}
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes the master net list
+/*! \brief Sort the master netlist
+ *
+ * This fcn takes the master net list
* sheet_head->master_net_list_head
* and sorts it in this order:
* <all nets in alphabetical order>
- *
- *------------------------------------------------------------------*/
+ */
void s_string_list_sort_master_net_list() {
int i = 0;
STRING_LIST *local_list;
@@ -437,13 +460,15 @@ void s_string_list_sort_master_net_list() {
}
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes the master net attrib list
+/*! \brief Sort the master net attribute list
+ *
+ * Take the master net attribute list
* sheet_head->master_net_attrib_list_head
- * and sorts it in this order:
+ * and sort it in this order:
* value, footprint, model-name, file,
- * <all other attribs in alphabetical order>
- *
- *------------------------------------------------------------------*/
+ * <all other attributes in alphabetical order>
+ */
+/*------------------------------------------------------------------*/
void s_string_list_sort_master_net_attrib_list() {
int i = 0;
STRING_LIST *local_list;
@@ -463,14 +488,16 @@ void s_string_list_sort_master_net_attrib_list() {
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes the master pin list
+/*! \brief Sort the master pin list
+ *
+ * Take the master pin list
* sheet_head->master_pin_list_head
* and sorts it in this order:
* <all refdeses in alphabetical order>
* Right now it does nothing other than fill in the "position"
* and "length" variables.
- *
- *------------------------------------------------------------------*/
+ */
+/*------------------------------------------------------------------*/
void s_string_list_sort_master_pin_list() {
int i = 0;
STRING_LIST *local_list, *p;
@@ -504,14 +531,16 @@ void s_string_list_sort_master_pin_list() {
}
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes the master pin attrib list
+/*! \brief Sort the master pin attribute list
+ *
+ * Takes the master pin attrib list
* sheet_head->master_pin_attrib_list_head
* and sorts it in this order:
* <all pin attribs in alphabetical order>
* Right now it does nothing other than fill in the "position"
* and "length" variables.
- *
- *------------------------------------------------------------------*/
+ */
+/*------------------------------------------------------------------*/
void s_string_list_sort_master_pin_attrib_list() {
int i = 0;
STRING_LIST *local_list;
diff --git a/gattrib/src/s_table.c b/gattrib/src/s_table.c
index 25fca77..47bbe80 100644
--- a/gattrib/src/s_table.c
+++ b/gattrib/src/s_table.c
@@ -17,12 +17,17 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns involved in manipulating the TABLE structure,
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions to manipulate the TABLE structure
+ *
+ * This file holds functions involved in manipulating the TABLE structure,
* which is subsidiary to SHEET_DATA. TABLE is a 2 dimensional array
* of structs; each struct corresponds to the data about an element
* in a single cell of the spreadsheet.
- *------------------------------------------------------------------*/
+ * \todo TABLE should also store its dimensions in its own data
+ * structure to save carrying the dimensions around separately.
+ */
#include <config.h>
@@ -35,7 +40,7 @@
/*------------------------------------------------------------------
* Gattrib specific includes
*------------------------------------------------------------------*/
-#include <libgeda/libgeda.h> /* geda library fcns */
+#include <libgeda/libgeda.h> /* geda library functions */
#include "../include/struct.h" /* typdef and struct declarations */
#include "../include/prototype.h" /* function prototypes */
#include "../include/globals.h"
@@ -47,15 +52,19 @@
/* =================== Public Functions ====================== */
/*------------------------------------------------------------------*/
-/*! \brief This fcn is the table creator. It returns a pointer to
+/*! \brief Create a new table
+ *
+ * This is the table creator. It returns a pointer to
* an initialized TABLE struct. As calling args, it needs
* the number of rows and cols to allocate. The table is a
* dynamically allocated 2D array of structs. To access data in
* a cell in the table, you reference (for example):
* ((sheet_data->comp_table)[i][j]).attrib_value
* (Parens used only for clarity. It works without parens.)
- *
- *------------------------------------------------------------------*/
+ * \param rows Number of rows required in the new table
+ * \param cols Number of columns required in the new table
+ * \returns a pointer to an initialized TABLE struct.
+ */
TABLE **s_table_new(int rows, int cols)
{
TABLE **new_table;
@@ -88,13 +97,21 @@ TABLE **s_table_new(int rows, int cols)
/*------------------------------------------------------------------*/
-/*! \brief This fcn recreates the table with
+/*! \brief Resize a TABLE
+ *
+ * This function recreates the table with
* a new size. It can only increase
* the number of cols. You can't increase the number of rows since
* gattrib doesn't allow you to input new components. Decreasing the
* number of cols is also TBD.
- *
- *------------------------------------------------------------------*/
+ * \param table Table to resize
+ * \param rows Number of rows in the table
+ * \param old_cols Number of columns previously in the table
+ * \param new_cols Number of columns required in the table
+ * \returns a pointer to the resized table
+ * \todo The row and column information could be stored in the
+ * TABLE struct.
+ */
TABLE **s_table_resize(TABLE **table,
int rows, int old_cols, int new_cols)
{
@@ -124,11 +141,15 @@ TABLE **s_table_resize(TABLE **table,
/*------------------------------------------------------------------*/
-/*! \brief This fcn destroys the old table.
+/*! \brief Destroy a table
+ *
+ * This function destroys the old table.
* Use it after reading in a new
* page to get rid of the old table before building a new one.
- *
- *------------------------------------------------------------------*/
+ * \param table Table to destroy
+ * \param row_count Number of rows in table
+ * \param col_count Number of columns in table
+ */
void s_table_destroy(TABLE **table, int row_count, int col_count)
{
int i, j;
@@ -157,12 +178,16 @@ void s_table_destroy(TABLE **table, int row_count, int col_count)
/*------------------------------------------------------------------*/
-/*! \brief This fcn returns the index number
+/*! \brief Get a string index number
+ *
+ * This function returns the index number
* when given a STRING_LIST and a
* string to match. It finds the index
* number by iterating through the master list.
- *
- *------------------------------------------------------------------*/
+ * \param local_list
+ * \param local_string
+ * \returns the index of the string
+ */
int s_table_get_index(STRING_LIST *local_list, char *local_string) {
int count = 0;
STRING_LIST *list_element;
@@ -186,13 +211,20 @@ int s_table_get_index(STRING_LIST *local_list, char *local_string) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn takes a table, a row list, and a row name,
+/*! \brief Create attribute pair
+ *
+ * This function takes a table, a row list, and a row name,
* and returns a list holding
* name=value pairs for all attribs pertainent to that particular
* row.
* If the row holds no attribs, it just returns NULL.
*
- *------------------------------------------------------------------*/
+ * \param row_name Name of the row to search for
+ * \param table Table to be searched
+ * \param row_list list of rows
+ * \param num_attribs
+ * \returns STRING_LIST of name=value pairs
+ */
STRING_LIST *s_table_create_attrib_pair(gchar *row_name,
TABLE **table,
STRING_LIST *row_list,
@@ -232,12 +264,14 @@ STRING_LIST *s_table_create_attrib_pair(gchar *row_name,
/*------------------------------------------------------------------*/
-/*! \brief This fcn iterates over adds all
+/*! \brief Add components to the component table
+ *
+ * This fcn iterates over adds all
* objects found on this page looking
* for components. When it finds a component, it finds all component
* attribs and sticks them in the TABLE.
- *
- *------------------------------------------------------------------*/
+ * \param obj_list pointer to GList containing objects on this page
+ */
void s_table_add_toplevel_comp_items_to_comp_table (const GList *obj_list) {
gchar *temp_uref;
int row, col;
@@ -345,12 +379,19 @@ void s_table_add_toplevel_comp_items_to_comp_table (const GList *obj_list) {
#if 0
/*------------------------------------------------------------------*/
-/*! \brief This fcn iterates over adds all
+/*! \brief Add nets to net table
+ *
+ * This function iterates over adds all
* items found on this page looking
* for nets and adds them individually to the net table. Looping over
* objects occurs here.
*
- *------------------------------------------------------------------*/
+ * \param start_obj Pointer to first object
+ *
+ * \todo Why do the calling semantics of this function disagree with
+ * s_table_add_toplevel_pin_items_to_pin_table()? That function
+ * takes a GList, this one takes a pointer to OBJECT.
+ */
void s_table_add_toplevel_net_items_to_net_table(OBJECT *start_obj) {
OBJECT *o_current;
char *temp_netname;
@@ -430,11 +471,13 @@ void s_table_add_toplevel_net_items_to_net_table(OBJECT *start_obj) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn iterates over adds all items found on this page
+/*! \brief Add pins to pin table.
+ *
+ * This function iterates over adds all items found on this page
* looking for pins. WHen it finds a pin, it gathers all
* pin attribs and sticks them into the pin table.
- *
- *------------------------------------------------------------------*/
+ * \param obj_list List of objects on page
+ */
void s_table_add_toplevel_pin_items_to_pin_table (const GList *obj_list) {
gchar *temp_uref;
gchar *pinnumber;
@@ -549,12 +592,13 @@ void s_table_add_toplevel_pin_items_to_pin_table (const GList *obj_list) {
/*------------------------------------------------------------------*/
-/*! \brief This fcn through the spreadsheet,
+/*! \brief Push spreadsheet data to TABLEs.
+ *
+ * This function traverses the spreadsheet,
* extracts the attribs from
* the cells, and places them back into TABLE. This is the
* first step in saving out a project.
- *
- *------------------------------------------------------------------*/
+ */
void s_table_gtksheet_to_all_tables() {
int num_rows;
@@ -616,12 +660,20 @@ void s_table_gtksheet_to_all_tables() {
/* =================== Private Functions ====================== */
/*------------------------------------------------------------------*/
-/*! \brief This fcn does the actual heaving lifting of looping
+/*! \brief Extract attributes from gtksheet into TABLE
+ *
+ * This function does the actual heavy lifting of looping
* through the spreadsheet, extracting the attribs from
* the cells, and placing them back into TABLE. This is the
* first step in saving out a project.
*
- *------------------------------------------------------------------*/
+ * \param local_gtk_sheet GtkSheet to save
+ * \param master_row_list STRING_LIST of rows
+ * \param master_col_list STRING_LIST of columns
+ * \param local_table TABLE structure to fill
+ * \param num_rows Number of rows in table
+ * \param num_cols Number of columns in table
+ */
void s_table_gtksheet_to_table(GtkSheet *local_gtk_sheet, STRING_LIST *master_row_list,
STRING_LIST *master_col_list, TABLE **local_table,
int num_rows, int num_cols)
diff --git a/gattrib/src/s_toplevel.c b/gattrib/src/s_toplevel.c
index c76385e..05c27b0 100644
--- a/gattrib/src/s_toplevel.c
+++ b/gattrib/src/s_toplevel.c
@@ -17,12 +17,16 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns involved in manipulating the TOPLEVEL data
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions to manipulate the TOPLEVEL struct.
+ *
+ * This file holds functions involved in manipulating the TOPLEVEL data
* structure. TOPLEVEL is the data structure inherited from gEDA's
* other programs, and holds all info about a project in a form
* native to gEDA.
- *------------------------------------------------------------------*/
+ */
+
#include <config.h>
@@ -35,7 +39,7 @@
/*------------------------------------------------------------------
* Gattrib specific includes
*------------------------------------------------------------------*/
-#include <libgeda/libgeda.h> /* geda library fcns */
+#include <libgeda/libgeda.h> /* geda library functions */
#include "../include/struct.h" /* typdef and struct declarations */
#include "../include/prototype.h" /* function prototypes */
#include "../include/globals.h"
@@ -48,10 +52,12 @@
/* =================== Public Functions ====================== */
-/*! \brief Reads in a page & calls f_open, which fills out the
- * pr_current structure.
+/*! \brief Read a schematic page
+ *
+ * Reads in a schematic page & calls f_open, which fills out the
+ * pr_current structure.
*
- * \param [in] filename file to be opened
+ * \param filename file to be opened
* \returns 1 on success, 0 on failure
*/
int s_toplevel_read_page(char *filename)
@@ -75,14 +81,16 @@ int s_toplevel_read_page(char *filename)
}
-/*! \brief This function loops through all components in the
- * design looking for components which are placeholders.
+/*! \brief Verify the entire design
+ *
+ * This function loops through all components in the
+ * design looking for components which are placeholders.
*
* Placeholders are inserted into the object list when
* no symbol file is found. If this function finds a
* placeholder, it warns the user.
*
- * \param [in] pr_current a toplevel object
+ * \param pr_current pointer to the toplevel object to be verified
*/
void s_toplevel_verify_design(TOPLEVEL *pr_current)
{
@@ -115,11 +123,15 @@ void s_toplevel_verify_design(TOPLEVEL *pr_current)
-/*------------------------------------------------------------------
- * This fcn returns 1 if the project is empty (i.e. pr_current is
+/*------------------------------------------------------------------*/
+/*! \brief Detect empty project
+ *
+ * Test if there is data in the current project.
+ * \returns 1 if the project is empty (i.e. pr_current is
* not filled out yet), and 0 if the project is non-empty (i.e. there
* is some data in pr_current).
- *------------------------------------------------------------------*/
+ * \todo Doesn't do anything. Candidate for removal?
+ */
void s_toplevel_empty_project()
{
/* Nothing here yet. Is this necessary in current program
@@ -128,12 +140,15 @@ void s_toplevel_empty_project()
-/*------------------------------------------------------------------
- * This fcn is called when the user invokes "save". It first
+/*------------------------------------------------------------------*/
+/*! \brief Copy data from gtksheet into TOPLEVEL struct
+ *
+ * Called when the user invokes "save". It first
* places all data from gtksheet into SHEET_DATA. Then it
- * loops through all pages & calls s_toplevel_sheetdata_to_toplevel to place all
+ * loops through all pages & calls s_toplevel_sheetdata_to_toplevel()
+ * to place all
* stuff in SHEET_DATA into the libgeda TOPLEVEL structure.
- *------------------------------------------------------------------*/
+ */
void
s_toplevel_gtksheet_to_toplevel()
{
@@ -171,15 +186,18 @@ s_toplevel_gtksheet_to_toplevel()
}
-/*------------------------------------------------------------------
- * This fcn gets called when the user has entered a new attrib name,
+/*------------------------------------------------------------------*/
+/*! \brief Add a new attribute to the top level
+ *
+ * This function gets called when the user has entered a new attrib name,
* and clicked the OK button. It does this:
- * 1. It figures out which attrib/sheet is being added to
- * 2. It destroys the old table in preparation for the new attrib.
- * 3. It adds the new attrib to the master lists.
- * 4. It creates a new table with the new attrib.
- * 5. It then adds the appropriate col to the gtksheet.
- *------------------------------------------------------------------*/
+ * -# It figures out which attrib/sheet is being added to
+ * -# It destroys the old table in preparation for the new attrib.
+ * -# It adds the new attrib to the master lists.
+ * -# It creates a new table with the new attrib.
+ * -# It then adds the appropriate col to the gtksheet.
+ * \param new_attrib_name attribute to be added
+ */
void s_toplevel_add_new_attrib(gchar *new_attrib_name) {
gint cur_page; /* current page in notbook */
gint old_comp_attrib_count;
@@ -262,11 +280,13 @@ void s_toplevel_add_new_attrib(gchar *new_attrib_name) {
}
-/*------------------------------------------------------------------
- * This fcn gets called when the user has selected a single attrib
+/*------------------------------------------------------------------*/
+/*! \brief Delete an attribute column
+ *
+ * This function gets called when the user has selected a single attrib
* column, selected the edit->delete attrib item from the pull-down
* menu, and then said "yes" to the confirm dialog.
- *------------------------------------------------------------------*/
+ */
void s_toplevel_delete_attrib_col() {
gint cur_page; /* current page in notbook */
gint mincol, maxcol;
@@ -363,14 +383,17 @@ void s_toplevel_delete_attrib_col() {
}
-/*------------------------------------------------------------------
- * This fcn is a hack. It gives a non-NULL value to the select_func
- * defined in globals.c for libgeda. A non-NULL value for this fcn
+/*------------------------------------------------------------------*/
+/*! \brief Select object in the top level.
+ *
+ * This function is a hack. It gives a non-NULL value to the select_func
+ * defined in globals.c for libgeda. A non-NULL value for this function
* makes sure that object->sel_func = 1 when the project is saved out,
* which keeps the objects selectable in gschem.
* Perhaps I should just set the variable myself when saving the
* project out . . . . .
- *------------------------------------------------------------------*/
+ * \todo Function is a NOP - candidate for removal?
+ */
void s_toplevel_select_object()
{
/* I don't know if I should do anything in here to prevent
@@ -378,20 +401,23 @@ void s_toplevel_select_object()
}
-/* ======================= Private fcns ====================== */
+/* ======================= Private functions ====================== */
-/*------------------------------------------------------------------
- * This fcn
+/*------------------------------------------------------------------*/
+/*! \brief Copy SHEET_DATA content to TOP_LEVEL
+ *
+ * This function
* loops through all objects on (PAGE page)->(OBJECT *start_obj).
* It takes the updated SHEET_DATA->TABLE data and then updates the
* objects with the new attribs & attrib values.
* For each component, it updates the attached
* attrib values using the updated values held in the SHEET_DATA->TABLE
* structure. It does so in three steps:
- * 1. First find and update component attribs.
- * 2. Then find and update net attribs.
- * 3. Finally find and update pin attribs.
- *------------------------------------------------------------------*/
+ * -# First find and update component attribs.
+ * -# Then find and update net attribs.
+ * -# Finally find and update pin attribs.
+ * \param page schematic page to copy
+ */
void
s_toplevel_sheetdata_to_toplevel (PAGE *page)
{
@@ -433,7 +459,8 @@ s_toplevel_sheetdata_to_toplevel (PAGE *page)
temp_uref = s_attrib_get_refdes(o_current);
if (temp_uref != NULL) {
/* Must create a name=value pair list for each particular component
- * which we can pass to fcn updating o_current. This fcn places all attribs
+ * which we can pass to function updating o_current. This function
+ * places all attribs
* found in the row into new_comp_attrib_pair_list. */
new_comp_attrib_pair_list = s_table_create_attrib_pair(temp_uref,
sheet_head->component_table,
@@ -519,11 +546,14 @@ s_toplevel_sheetdata_to_toplevel (PAGE *page)
}
-/*------------------------------------------------------------------
- * This fcn returns a list of attributes attached to obj_name = comp
- * refdes or netlist. The returned list is a STRING_LIST where the
- * ->data holds a name=value string.
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*! \brief Get the component attributes from the top level
+ *
+ * This function returns a list of attributes attached to obj_name = comp
+ * refdes or netlist.
+ * \param refdes component refdes to return values from
+ * \returns a STRING_LIST where the data field holds a name=value string.
+ */
STRING_LIST *s_toplevel_get_component_attribs_in_sheet(char *refdes)
{
STRING_LIST *new_attrib_list;
@@ -589,29 +619,28 @@ STRING_LIST *s_toplevel_get_component_attribs_in_sheet(char *refdes)
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*! \brief Update component attributes in TOP_LEVEL
+ *
* For each attrib string attached to the component, update it using the value
* held in new_comp_attrib_list. Algorithm:
- * 1. Form list of all component attribs held on both the component
- * (o_current), as well as in the attrib list (SHEET_DATA).
- * 2. Loop over name=value pairs held in complete_comp_attrib_list.
- * 3. For each name=value pair, look for corresponding attrib on o_current.
- * 4. For each name=value pair, look for the corresponding attrib in
- * new_comp_attrib_list.
- * 5. If the attrib exists on o_current and in new_comp_attrib_list, write the
- * new value (from new_comp_attrib_list) into o_current.
- * 6. If the attrib exists on o_current, but is null in name=value pair,
- * delete the attrib from o_current.
- * 7. If the attribs doesn't exist on o_current, but is non-null in
- * the name=value pair, create an attrib object and add it to the part
- * on o_current.
- *
- * Calling args: OBJECT *o_current -- component (complex) to be updated.
- * STRING_LIST *new_comp... -- list of name=value attribute pairs
- * from SHEET_DATA.
- * Returns: Returns nothing because the changes are made in o_current, which
- * is part of the global TOPLEVEL pr_current.
- *------------------------------------------------------------------*/
+ * -# Form list of all component attribs held on both the component
+ * (o_current), as well as in the attrib list (SHEET_DATA).
+ * -# Loop over name=value pairs held in complete_comp_attrib_list.
+ * -# For each name=value pair, look for corresponding attrib on o_current.
+ * -# For each name=value pair, look for the corresponding attrib in
+ * new_comp_attrib_list.
+ * -# If the attrib exists on o_current and in new_comp_attrib_list, write the
+ * new value (from new_comp_attrib_list) into o_current.
+ * -# If the attrib exists on o_current, but is null in name=value pair,
+ * delete the attrib from o_current.
+ * -# If the attribs doesn't exist on o_current, but is non-null in
+ * the name=value pair, create an attrib object and add it to the part
+ * on o_current.
+ * \param o_current Component (complex) to be updated.
+ * \param new_comp_attrib_list list of name=value attribute pairs
+ * from SHEET_DATA.
+ */
void s_toplevel_update_component_attribs_in_toplevel(OBJECT *o_current,
STRING_LIST *new_comp_attrib_list)
{
@@ -625,7 +654,7 @@ void s_toplevel_update_component_attribs_in_toplevel(OBJECT *o_current,
gchar *refdes;
GList *a_iter;
OBJECT *a_current;
- int count = 0; /* This is to fake out a fcn called later */
+ int count = 0; /* This is to fake out a function called later */
gint row, col;
gint visibility = 0;
gint show_name_value = 0;
@@ -688,7 +717,7 @@ void s_toplevel_update_component_attribs_in_toplevel(OBJECT *o_current,
/*
- *Now the main business of this fcn: updating the attribs attached to this o_current.
+ *Now the main business of this function: updating the attribs attached to this o_current.
* Loop on name=value pairs held in complete_comp_attrib_list , and then use this to get the
* name=value pairs out of new_comp_attrib_list and from o_current.
*/
@@ -813,9 +842,10 @@ void s_toplevel_update_component_attribs_in_toplevel(OBJECT *o_current,
}
-/*------------------------------------------------------------------
- *
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*!
+ * \todo Function doesn't do anything - candidate for removal?
+ */
STRING_LIST *s_toplevel_get_net_attribs_in_sheet(char *netname)
{
/* must be filled in */
@@ -823,9 +853,10 @@ STRING_LIST *s_toplevel_get_net_attribs_in_sheet(char *netname)
}
-/*------------------------------------------------------------------
- *
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*!
+ * \todo Function doesn't do anything - candidate for removal?
+ */
void s_toplevel_update_net_attribs_in_toplevel(OBJECT *o_current,
STRING_LIST *new_net_attrib_list)
{
@@ -834,17 +865,23 @@ void s_toplevel_update_net_attribs_in_toplevel(OBJECT *o_current,
}
-/*------------------------------------------------------------------
- * This fcn takes a pointer to the OBJECT pin, and returns a list
+/*------------------------------------------------------------------*/
+/*! \brief Get pin attributes
+ *
+ * This function takes a pointer to the OBJECT pin, and returns a list
* of attribs found attached to the pin. The returned list is a
* STRING_LIST where the ->data holds a name=value string.
* The algorithm is as follows:
- * 1. Form refdes:pinnumber label for this pin.
- * 2. Get row number of this refdes:pinnumber
- * 3. Create a list of name=value pairs from entries in the pin_table
- * on this row.
- * 4. Return list of name=value pairs found.
- *------------------------------------------------------------------*/
+ * -# Form refdes:pinnumber label for this pin.
+ * -# Get row number of this refdes:pinnumber
+ * -# Create a list of name=value pairs from entries in the pin_table
+ * on this row.
+ * -# Return list of name=value pairs found.
+ *
+ * \param refdes Ref des string
+ * \param pin Pin object
+ * \returns name=value pair as a STRING_LIST
+ */
STRING_LIST *s_toplevel_get_pin_attribs_in_sheet(char *refdes, OBJECT *pin)
{
STRING_LIST *new_attrib_list;
@@ -922,20 +959,23 @@ STRING_LIST *s_toplevel_get_pin_attribs_in_sheet(char *refdes, OBJECT *pin)
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*! \brief Update pin attributes in toplevel
+ *
* For each attrib string attached to the pin, update it using the value
* held in new_pin_attrib_list. Algorithm:
- * 1. Loop over name=value pairs held in new_pin_attrib_list.
- * 2. For each name=value pair, look for corresponding attrib on pin.
- * 3. If the attrib exists on pin and in name=value pair, write the
- * new value in.
- * 4. If the attrib exists on pin, but is null in name=value pair,
- * delete the attrib.
- * 5. If the attribs doesn't exist on pin, but is non-null in
- * the name=value pair, create an attrib object and add it to the pin.
- * Returns: Returns nothing because the changes are made in o_pin, which
- * is part of the global TOPLEVEL pr_current.
- *------------------------------------------------------------------*/
+ * -# Loop over name=value pairs held in new_pin_attrib_list.
+ * -# For each name=value pair, look for corresponding attrib on pin.
+ * -# If the attrib exists on pin and in name=value pair, write the
+ * new value in.
+ * -# If the attrib exists on pin, but is null in name=value pair,
+ * delete the attrib.
+ * -# If the attribs doesn't exist on pin, but is non-null in
+ * the name=value pair, create an attrib object and add it to the pin.
+ * \param refdes Unused - needs refactored out
+ * \param [in,out] o_pin pin to update
+ * \param [in] new_pin_attrib_list New pin attribute list to apply
+ */
void s_toplevel_update_pin_attribs_in_toplevel(char *refdes, OBJECT *o_pin,
STRING_LIST *new_pin_attrib_list)
{
diff --git a/gattrib/src/s_visibility.c b/gattrib/src/s_visibility.c
index e35b63c..083ca5f 100644
--- a/gattrib/src/s_visibility.c
+++ b/gattrib/src/s_visibility.c
@@ -16,10 +16,15 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds widgets and fcns used in conjunction
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions to manipulate attribute visibility
+ *
+ * This file holds widgets and functions used in conjunction
* with setting attribute visibility.
- *------------------------------------------------------------------*/
+ * \todo There seems to be a lot of duplicated code in this file -
+ * a good candidate for refactoring.
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
@@ -79,13 +84,15 @@
-/* ---------------------------------------------------------------------- *
- * s_visibility_set_invisible -- This sets the selected cells to
- * INVISIBLE.
- * This fcn is called from the menu, it assumes you have
+/* ---------------------------------------------------------------------- */
+/* \brief Set the selected cells to INVISIBLE
+ *
+ *
+ * This sets the selected cells to INVISIBLE.
+ * This function is called from the menu, it assumes you have
* selected a range of cells which are carried in the global
* variable "sheet".
- * ---------------------------------------------------------------------- */
+ */
void s_visibility_set_invisible() {
gint i, j;
gint row_start, row_end, col_start, col_end;
@@ -151,12 +158,14 @@ void s_visibility_set_invisible() {
}
-/* ---------------------------------------------------------------------- *
- * s_visibility_set_name_only -- This sets the selected cells to NAME_ONLY.
- * This fcn is invoked from the menu, it assumes you have
+/* ---------------------------------------------------------------------- */
+/*! \brief Set the visibility of the selected cells to NAME_ONLY.
+ *
+ * This sets the selected cells to NAME_ONLY.
+ * This function is invoked from the menu, it assumes you have
* selected a range of cells which are carried in the global
* variable "sheet".
- * ---------------------------------------------------------------------- */
+ */
void s_visibility_set_name_only() {
gint i, j;
gint row_start, row_end, col_start, col_end;
@@ -210,12 +219,14 @@ void s_visibility_set_name_only() {
}
}
-/* ---------------------------------------------------------------------- *
+/* ---------------------------------------------------------------------- */
+/* \brief Set the selected cells' visibility to VALUE_ONLY
+ *
* s_visibility_set_value_only -- This sets the selected cells to VALUE_ONLY.
* This fcn is invoked from the menu, it assumes you have
* selected a range of cells which are carried in the global
* variable "sheet".
- * ---------------------------------------------------------------------- */
+ */
void s_visibility_set_value_only() {
gint i, j;
gint row_start, row_end, col_start, col_end;
@@ -271,13 +282,16 @@ void s_visibility_set_value_only() {
}
}
-/* ---------------------------------------------------------------------- *
- * s_visibility_set_name_and_value -- This sets the selected cells
+/* ---------------------------------------------------------------------- */
+/* \brief Set the visibility of the selected cells to NAME_AND_VALUE
+ *
+ * This sets the selected cells
* to NAME_AND_VALUE
* This fcn is invoked from the menu, it assumes you have
* selected a range of cells which are carried in the global
* variable "sheet".
- * ---------------------------------------------------------------------- */
+ *
+ */
void s_visibility_set_name_and_value() {
gint i, j;
gint row_start, row_end, col_start, col_end;
@@ -332,10 +346,17 @@ void s_visibility_set_name_and_value() {
/* ================== Private functions =================== */
-/* ---------------------------------------------------------------------- *
- * s_visibility_set_cell -- this sets the visibility of an individual cell
+/* ---------------------------------------------------------------------- */
+/* \brief set the visibility of an individual cell
+ *
+ * Set the visibility of an individual cell
* to "state". The cell is identified by (row, col)
- * ---------------------------------------------------------------------- */
+ * \param cur_page index of spreadsheet tab
+ * \param row Row index of target cell
+ * \param col Column index of target cell
+ * \param visibility Visibility value to set cell to
+ * \param show_name_value Name, Value visibility flag
+ */
void s_visibility_set_cell(gint cur_page, gint row, gint col,
gint visibility,
gint show_name_value) {
diff --git a/gattrib/src/x_dialog.c b/gattrib/src/x_dialog.c
index 9766634..5030788 100644
--- a/gattrib/src/x_dialog.c
+++ b/gattrib/src/x_dialog.c
@@ -17,9 +17,12 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns used to display dialog boxes.
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions used to display dialog boxes.
+ *
+ * Functions used to display dialog boxes.
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
@@ -60,7 +63,9 @@
#endif
-/*! \brief This asks for the name of the attrib column to insert
+/*! \brief Add new attribute dialog.
+ *
+ * This asks for the name of the attrib column to insert
* and then inserts the column.
*/
void x_dialog_newattrib()
@@ -112,7 +117,9 @@ void x_dialog_newattrib()
}
-/*! \brief This function throws up the "Delete foo, are you sure?" dialog
+/*! \brief Delete Attribute dialog
+ *
+ * This function throws up the "Delete foo, are you sure?" dialog
* box. It offers two buttons: "yes" and "cancel".
*/
void x_dialog_delattrib()
@@ -158,7 +165,9 @@ void x_dialog_delattrib()
gtk_widget_destroy(dialog);
}
-/*! \brief This is the "missing symbol file found on object" dialog.
+/*! \brief Missing Symbol dialog
+ *
+ * This is the "missing symbol file found on object" dialog.
*
* It offers the user the chance to close the project without
* saving because he read a schematic with a missing symbol file.
@@ -200,7 +209,9 @@ void x_dialog_missing_sym()
gtk_widget_destroy(dialog);
}
-/*! \brief This is the "Unsaved data -- are you sure you want to quit?" dialog
+/*! \brief Unsaved data dialog
+ *
+ * This is the "Unsaved data -- are you sure you want to quit?" dialog
* box which is thrown up before the user quits.
*/
void x_dialog_unsaved_data()
@@ -261,7 +272,9 @@ void x_dialog_unsaved_data()
return;
}
-/*! \brief This function informs the user that he has chosen an unimplemented
+/*! \brief Unimplemented feature dialog
+ *
+ * This function informs the user that he has chosen an unimplemented
* feature. It presents only an "OK" button to leave.
*/
void x_dialog_unimplemented_feature()
@@ -287,12 +300,14 @@ void x_dialog_unimplemented_feature()
gtk_widget_destroy(dialog);
}
-/*! \brief This function displays a dialog with the error string and
- * terminates the program.
+/*! \brief Fatal error dialog
+ *
+ * This function displays a dialog with the error string and
+ * terminates the program.
*
* \param [in] string the error string
* \param [in] return_code the exit code
- * \return this function never returns
+ * \todo Is the GPOINTER_TO_INT() call needed in exit()?
*/
void x_dialog_fatal_error(gchar *string, gint return_code)
{
@@ -314,7 +329,9 @@ void x_dialog_fatal_error(gchar *string, gint return_code)
exit(GPOINTER_TO_INT(return_code));
}
-/*! \brief This dosplays the about dialog.
+/*! \brief About gattrib dialog
+ *
+ * This dosplays the about dialog.
*/
void x_dialog_about_dialog()
{
@@ -340,7 +357,9 @@ void x_dialog_about_dialog()
gtk_widget_destroy(dialog);
}
-/*! \brief This asks for the filename for the CSV export file and then
+/*! \brief Export file dialog
+ *
+ * This asks for the filename for the CSV export file and then
* does the exporting.
*/
void x_dialog_export_file()
diff --git a/gattrib/src/x_fileselect.c b/gattrib/src/x_fileselect.c
index 04a9184..e7eeca1 100644
--- a/gattrib/src/x_fileselect.c
+++ b/gattrib/src/x_fileselect.c
@@ -16,11 +16,14 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions to display file open/save dialog box.
+ *
* This file holds fcns used to display the file open/save dialog box.
* It was cloned from x_fileselect.c in gschem/src, and then hacked
* by SDB for use in gattrib.
- *------------------------------------------------------------------*/
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
@@ -79,9 +82,12 @@
/* ----- x_fileselect stuff begins here ----- */
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*! \brief Set up file filter for the file chooser
+ *
* This fcn creates and sets the file filter for the filechooser.
- *------------------------------------------------------------------*/
+ * \param filechooser GtkFileChooser to set up
+ */
static void
x_fileselect_setup_filechooser_filters (GtkFileChooser *filechooser)
{
@@ -111,11 +117,11 @@ x_fileselect_setup_filechooser_filters (GtkFileChooser *filechooser)
}
-/*! \brief Open all files specified in the list. The caller
- * is responsible for freeing the strings and the list
- * itself.
+/*! \brief Open all files specified in the list.
+ *
+ * Open all files specified in the list. The caller is responsible for
+ * freeing the strings and the list itself.
*
- * \par Function Description
* The function updates the user interface. At the end of the function,
* the toplevel's current page is set to the page of the last loaded page.
*
@@ -218,7 +224,9 @@ x_fileselect_load_files (GSList *filenames)
return TRUE;
}
-/*! \brief This function opens a file chooser dialog and waits for the user
+/*! \brief Open file dialog
+ *
+ * This function opens a file chooser dialog and waits for the user
* to select at least one file to load as toplevel's new pages.
*
* \returns list of files to be opened, or NULL if the user cancelled
@@ -258,7 +266,9 @@ x_fileselect_open (void)
return filenames;
}
-/*------------------------------------------------------------------
+/*------------------------------------------------------------------*/
+/*! \brief File save dialog
+ *
* This function opens a file chooser dialog and wait for the user to
* select a file where the toplevel's current page will be
* saved.
@@ -267,7 +277,7 @@ x_fileselect_open (void)
* page is not saved.
*
* The function updates the user interface.
- *------------------------------------------------------------------*/
+ */
void
x_fileselect_save (void)
{
diff --git a/gattrib/src/x_gtksheet.c b/gattrib/src/x_gtksheet.c
index ec7e949..2996a6f 100644
--- a/gattrib/src/x_gtksheet.c
+++ b/gattrib/src/x_gtksheet.c
@@ -17,11 +17,14 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns used to handle the spreadsheet widget.
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions to interface to the spreadsheet widget.
+ *
+ * This file holds functions used to handle the spreadsheet widget.
* Much of this was hacked from testgtksheet.c starting in Jan 2004
* by SDB.
- *------------------------------------------------------------------*/
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
@@ -62,7 +65,9 @@
static void show_entry(GtkWidget *widget, gpointer data);
-/*! \brief Creates and initializes the GtkSheet widget, which is the
+/*! \brief Create the GtkSheet
+ *
+ * Creates and initializes the GtkSheet widget, which is the
* spreadsheet widget used for displaying the data.
*/
void
@@ -152,9 +157,14 @@ x_gtksheet_init()
-/*------------------------------------------------------------------
- * x_gtksheet_add_row_labels
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*! \brief Add row labels to GtkSheet
+ *
+ * Add row labels to GtkSheet
+ * \param sheet Pointer to the GtkSheet object
+ * \param count Number of row labels to add
+ * \param list_head Top of the string list
+ */
void
x_gtksheet_add_row_labels(GtkSheet *sheet, int count, STRING_LIST *list_head)
{
@@ -193,9 +203,14 @@ x_gtksheet_add_row_labels(GtkSheet *sheet, int count, STRING_LIST *list_head)
}
-/*------------------------------------------------------------------
- * x_gtksheet_add_col_labels
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*! \brief Add column labels to GtkSheet
+ *
+ * Add column labels to GtkSheet.
+ * \param sheet GtkSheet to add columns to
+ * \param count
+ * \param list_head pointer to top of STRING_LIST
+ */
void
x_gtksheet_add_col_labels(GtkSheet *sheet, int count, STRING_LIST *list_head)
{
@@ -218,9 +233,17 @@ x_gtksheet_add_col_labels(GtkSheet *sheet, int count, STRING_LIST *list_head)
}
-/*------------------------------------------------------------------
- * x_gtksheet_add_cell_item:
- *------------------------------------------------------------------*/
+/*------------------------------------------------------------------*/
+/*! \brief Add a cell item to the GtkSheet
+ *
+ * Add a cell item to the GtkSheet
+ * \param sheet GtkSheet to add the cell item to
+ * \param i
+ * \param j
+ * \param text
+ * \param visibility
+ * \param show_name_value
+ */
void
x_gtksheet_add_cell_item(GtkSheet *sheet,gint i, gint j,
gchar *text,
@@ -257,8 +280,14 @@ x_gtksheet_add_cell_item(GtkSheet *sheet,gint i, gint j,
}
-/*! \brief Returns the index of the first column selected, or -1 if
+/*! \brief Get the first column selected in the GtkSheet
+ *
+ * Get the first column selected in the GtkSheet
+ * Returns the index of the first column selected, or -1 if
* no column is selected.
+ * \param sheet GtkSheet to query
+ * \returns index of the first column selected, or -1 if
+ * no column is selected.
*/
int x_gtksheet_get_min_col(GtkSheet *sheet) {
if (sheet->state == GTK_SHEET_COLUMN_SELECTED) {
@@ -269,7 +298,11 @@ int x_gtksheet_get_min_col(GtkSheet *sheet) {
}
-/*! \brief Returns the index of the last column selected, or -1 if
+/*! \brief Get the last column selected in the GtkSheet
+ *
+ * Get the last column selected in the GtkSheet
+ * \param GtkSheet to query
+ * \returns the index of the last column selected, or -1 if
* no column is selected.
*/
int x_gtksheet_get_max_col(GtkSheet *sheet) {
@@ -281,7 +314,13 @@ int x_gtksheet_get_max_col(GtkSheet *sheet) {
}
-/*! \brief Sets the color of a cell identified by row, col.
+/*! \brief Set the text color of a cell
+ *
+ * Sets the color of a cell identified by row, col.
+ * \param sheet GtkSheet to operate on
+ * \param row Row of cell to set
+ * \param col Column of cell to set
+ * \param color_name Color to set text to
*/
void x_gtksheet_set_cell_text_color(GtkSheet *sheet, gint row, gint col,
gint color_name)
@@ -339,9 +378,13 @@ void x_gtksheet_set_cell_text_color(GtkSheet *sheet, gint row, gint col,
}
-/*! \brief Displays a text entry box at the top of the working area.
+/*! \brief Show text entry box
+ *
+ * Displays a text entry box at the top of the working area.
* It is removed since it is not needed now, but may come in
* handy later. Therefore I keep the code around.
+ * \param widget
+ * \param data
*/
static void
show_entry(GtkWidget *widget, gpointer data)
diff --git a/gattrib/src/x_window.c b/gattrib/src/x_window.c
index 62173bf..4bf3cfe 100644
--- a/gattrib/src/x_window.c
+++ b/gattrib/src/x_window.c
@@ -17,11 +17,14 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
-/*------------------------------------------------------------------
- * This file holds fcns used to handle the toplevel window and
+/*------------------------------------------------------------------*/
+/*! \file
+ * \brief Functions for the toplevel window
+ *
+ * This file holds functions used to handle the toplevel window and
* various widgets held by that window. Widges used to handle
* (GtkSheet *sheet) itself are held in a different file.
- *------------------------------------------------------------------*/
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
@@ -65,7 +68,9 @@ x_window_create_menu(GtkWindow *window, GtkWidget **menubar);
static void
x_window_set_default_icon( void );
-/*! \brief This function initializes the toplevel gtksheet stuff.
+/*! \brief Initialises the toplevel gtksheet
+ *
+ * This function initializes the toplevel gtksheet stuff.
*
* It basically just initializes the following widgets:
* GTK_WINDOW *window
@@ -121,10 +126,13 @@ x_window_init()
/*------------------------------------------------------------------
- * TODO: this should really be done in two stages:
- * 1. close the current project and reinitialize structures
- * 2. load the new projec:t
- *------------------------------------------------------------------*/
+ * \brief File Open menu
+ *
+ * File open menu. Currently unimplemented.
+ * \todo this should really be done in two stages:
+ * -# close the current project and reinitialize structures
+ * -# load the new project
+ */
static void
menu_file_open()
{
@@ -142,6 +150,11 @@ menu_file_open()
#endif
}
+/*!
+ * \brief File->Save menu item
+ *
+ * Implement the File->Save menu
+ */
static void
menu_file_save()
{
@@ -151,6 +164,11 @@ menu_file_save()
sheet_head->CHANGED = FALSE;
}
+/*!
+ * \brief File->Export CSV menu item
+ *
+ * Implement the File->Export CSV menu item
+ */
static void
menu_file_export_csv()
{
@@ -168,6 +186,11 @@ menu_file_export_csv()
}
}
+/*!
+ * \brief Edit->New attrib menu item
+ *
+ * Implement the New attrib menu item
+ */
static void
menu_edit_newattrib()
{
@@ -182,12 +205,20 @@ menu_edit_newattrib()
}
}
+/*!
+ * \brief Edit->Delete Attribute menu item
+ *
+ * Implements the Delete Attribute menu item
+ */
static void
menu_edit_delattrib()
{
x_dialog_delattrib();
}
+/*!
+ * The Gtk action table
+ */
static const GtkActionEntry actions[] = {
/* name, stock-id, label, accelerator, tooltip, callback function */
/* File menu */
@@ -219,7 +250,9 @@ static const GtkActionEntry actions[] = {
};
-/*! \brief Create the menu bar and attach it to the main window.
+/*! \brief Create and attach the menu bar
+ *
+ * Create the menu bar and attach it to the main window.
*
* First, the GtkActionGroup object is created and filled with
* entries of type GtkActionEntry (each entry specifies a single
@@ -228,6 +261,8 @@ static const GtkActionEntry actions[] = {
* description. Finally, the GtkAccelGroup is added to the
* main window to enable keyboard accelerators and a pointer
* to the menu bar is retrieved from the GtkUIManager object.
+ * \param window Window to add the menubar to
+ * \param [out] menubar Created menubar
*/
static void
x_window_create_menu(GtkWindow *window, GtkWidget **menubar)
@@ -263,20 +298,21 @@ x_window_create_menu(GtkWindow *window, GtkWidget **menubar)
}
-/*! \brief This function updates the top level window
+/*! \brief Add all items to the top level window
+ *
+ * This function updates the top level window
* after a new page is read in.
*
- * \par Function Description
* It does the following:
*
- * 2. Create a new gtksheet having the current dimensions.
- * 3. Call x_gktsheet_add_row_labels(comp_count, master_*_list_head)
- * 4. Call x_gktsheet_add_col_labels(comp_attrib_count, master_*_attrib_list_head)
- * 5. Call x_gktsheet_add_row_labels(net_count, master_*_list_head)
- * 6. Call x_gktsheet_add_col_labels(net_attrib_count, master_*_attrib_list_head)
- * 7. loop on i, j -- call x_gtksheet_add_entry(i, j, attrib_value)
- * 8. Call gtk_widget_show(window) to show new window.
- *------------------------------------------------------------------*/
+ * -# Create a new gtksheet having the current dimensions.
+ * -# Call x_gktsheet_add_row_labels(comp_count, master_*_list_head)
+ * -# Call x_gktsheet_add_col_labels(comp_attrib_count, master_*_attrib_list_head)
+ * -# Call x_gktsheet_add_row_labels(net_count, master_*_list_head)
+ * -# Call x_gktsheet_add_col_labels(net_attrib_count, master_*_attrib_list_head)
+ * -# loop on i, j -- call x_gtksheet_add_entry(i, j, attrib_value)
+ * -# Call gtk_widget_show(window) to show new window.
+ */
void
x_window_add_items()
{
@@ -393,9 +429,10 @@ x_window_add_items()
}
-/*! \brief Setup default icon for GTK windows
+/*! \brief Set application icon
+ *
+ * Setup default icon for GTK windows
*
- * \par Function Description
* Sets the default window icon by name, to be found in the current icon
* theme. The name used is #defined above as GATTRIB_THEME_ICON_NAME.
*/
_______________________________________________
geda-cvs mailing list
geda-cvs@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-cvs