From 02bcce261a81b4bf8116c4a66068bbc58688dee0 Mon Sep 17 00:00:00 2001 From: Bert Timmerman Date: Fri, 6 Jan 2012 21:55:32 +0100 Subject: [PATCH 1/1] src/file.c: Converted plain comments into doxygen comments. Signed-off-by: Bert Timmerman --- src/file.c | 204 ++++++++++++++++++++++++++++++++---------------------------- 1 files changed, 110 insertions(+), 94 deletions(-) diff --git a/src/file.c b/src/file.c index 1f5c406..3c745a1 100644 --- a/src/file.c +++ b/src/file.c @@ -153,9 +153,13 @@ static char *pcb_basename (char *p); */ -/* Hole[] in Polygon. */ +/*! + * Hole[] in Polygon. + */ #define PCB_FILE_VERSION_HOLES 20100606 -/* First version ever saved. */ +/*! + * First version ever saved. + */ #define PCB_FILE_VERSION_BASELINE 20091103 int @@ -245,8 +249,8 @@ sort_netlist () netlist_sort_offset = 0; } -/* --------------------------------------------------------------------------- - * opens a file and check if it exists +/*! + * \brief Opens a file and check if it exists. */ FILE * CheckAndOpenFile (char *Filename, bool Confirm, bool AllButton, @@ -291,8 +295,8 @@ CheckAndOpenFile (char *Filename, bool Confirm, bool AllButton, return (fp); } -/* --------------------------------------------------------------------------- - * opens a file for saving connection data +/*! + * \brief Opens a file for saving connection data. */ FILE * OpenConnectionDataFile (void) @@ -325,8 +329,8 @@ OpenConnectionDataFile (void) return fp; } -/* --------------------------------------------------------------------------- - * save elements in the current buffer +/*! + * \brief Save elements in the current buffer. */ int SaveBufferElements (char *Filename) @@ -341,8 +345,8 @@ SaveBufferElements (char *Filename) return (result); } -/* --------------------------------------------------------------------------- - * save PCB +/*! + * \brief Save PCB. */ int SavePCB (char *file) @@ -359,10 +363,11 @@ SavePCB (char *file) return retcode; } -/* --------------------------------------------------------------------------- - * set the route style to the first one, if the current one doesn't - * happen to match any. This way, "revert" won't change the route - * style. +/*! + * \brief Set the route style to the first one, if the current one + * doesn't happen to match any. + * + * This way, "revert" won't change the route style. */ static void set_some_route_style () @@ -375,10 +380,11 @@ set_some_route_style () SetKeepawayWidth (PCB->RouteStyle[0].Keepaway); } -/* --------------------------------------------------------------------------- - * load PCB - * parse the file with enabled 'PCB mode' (see parser) - * if successful, update some other stuff +/*! + * \brief Load PCB. + * + * Parse the file with enabled 'PCB mode' (see parser) + * if successful, update some other stuff. * * If revert is true, we pass "revert" as a parameter * to the HID's PCBChanged action. @@ -476,8 +482,8 @@ real_load_pcb (char *Filename, bool revert) return (1); } -/* --------------------------------------------------------------------------- - * Load PCB +/*! + * \brief Load PCB. */ int LoadPCB (char *file) @@ -485,8 +491,8 @@ LoadPCB (char *file) return real_load_pcb (file, false); } -/* --------------------------------------------------------------------------- - * Revert PCB +/*! + * \brief Revert PCB. */ int RevertPCB (void) @@ -536,8 +542,8 @@ PostLoadElementPCB () yyPCB->is_footprint = 1; } -/* --------------------------------------------------------------------------- - * writes the quoted string created by another subroutine +/*! + * \brief Writes the quoted string created by another subroutine. */ static void PrintQuotedString (FILE * FP, char *S) @@ -548,8 +554,8 @@ PrintQuotedString (FILE * FP, char *S) fputs (ds.Data, FP); } -/* --------------------------------------------------------------------------- - * writes out an attribute list +/*! + * \brief Writes out an attribute list. */ static void WriteAttributeList (FILE * FP, AttributeListType *list, char *prefix) @@ -561,8 +567,8 @@ WriteAttributeList (FILE * FP, AttributeListType *list, char *prefix) prefix, list->List[i].name, list->List[i].value); } -/* --------------------------------------------------------------------------- - * writes layout header information +/*! + * \brief Writes layout header information. */ static void WritePCBInfoHeader (FILE * FP) @@ -575,10 +581,11 @@ WritePCBInfoHeader (FILE * FP) */ } -/* --------------------------------------------------------------------------- - * writes data header - * the name of the PCB, cursor location, zoom and grid - * layergroups and some flags +/*! + * \brief Writes data header. + * + * The name of the PCB, cursor location, zoom and grid + * layergroups and some flags. */ static void WritePCBDataHeader (FILE * FP) @@ -625,8 +632,8 @@ WritePCBDataHeader (FILE * FP) PCB->RouteStyle[group].Hole, PCB->RouteStyle[group].Keepaway); } -/* --------------------------------------------------------------------------- - * writes font data of non empty symbols +/*! + * \brief Writes font data of non empty symbols. */ static void WritePCBFontData (FILE * FP) @@ -654,8 +661,8 @@ WritePCBFontData (FILE * FP) } } -/* --------------------------------------------------------------------------- - * writes via data +/*! + * \brief Writes via data. */ static void WriteViaData (FILE * FP, DataType *Data) @@ -672,8 +679,8 @@ WriteViaData (FILE * FP, DataType *Data) } } -/* --------------------------------------------------------------------------- - * writes rat-line data +/*! + * \brief Writes rat-line data. */ static void WritePCBRatData (FILE * FP) @@ -690,8 +697,8 @@ WritePCBRatData (FILE * FP) } } -/* --------------------------------------------------------------------------- - * writes netlist data +/*! + * \brief Writes netlist data. */ static void WritePCBNetlistData (FILE * FP) @@ -723,8 +730,8 @@ WritePCBNetlistData (FILE * FP) } } -/* --------------------------------------------------------------------------- - * writes element data +/*! + * \brief Writes element data. */ static void WriteElementData (FILE * FP, DataType *Data) @@ -806,8 +813,8 @@ WriteElementData (FILE * FP, DataType *Data) } } -/* --------------------------------------------------------------------------- - * writes layer data +/*! + * \brief Writes layer data. */ static void WriteLayerData (FILE * FP, Cardinal Number, LayerType *layer) @@ -885,8 +892,8 @@ WriteLayerData (FILE * FP, Cardinal Number, LayerType *layer) } } -/* --------------------------------------------------------------------------- - * writes just the elements in the buffer to file +/*! + * \brief Writes just the elements in the buffer to file. */ static int WriteBuffer (FILE * FP) @@ -900,8 +907,8 @@ WriteBuffer (FILE * FP) return (STATUS_OK); } -/* --------------------------------------------------------------------------- - * writes PCB to file +/*! + * \brief Writes PCB to file. */ static int WritePCB (FILE * FP) @@ -922,8 +929,8 @@ WritePCB (FILE * FP) return (STATUS_OK); } -/* --------------------------------------------------------------------------- - * writes PCB to file +/*! + * \brief Writes PCB to file. */ static int WritePCBFile (char *Filename) @@ -941,9 +948,11 @@ WritePCBFile (char *Filename) return (result); } -/* --------------------------------------------------------------------------- - * writes to pipe using the command defined by Settings.SaveCommand - * %f are replaced by the passed filename +/*! + * \brief Writes to pipe using the command defined by + * Settings.SaveCommand. + * + * %f are replaced by the passed filename. */ static int WritePipe (char *Filename, bool thePcb) @@ -1007,10 +1016,11 @@ WritePipe (char *Filename, bool thePcb) return (fclose (fp) ? STATUS_ERROR : result); } -/* --------------------------------------------------------------------------- - * saves the layout in a temporary file - * this is used for fatal errors and does not call the program specified - * in 'saveCommand' for safety reasons +/*! + * \brief Saves the layout in a temporary file. + * + * This is used for fatal errors and does not call the program specified + * in 'saveCommand' for safety reasons. */ void SaveInTMP (void) @@ -1026,9 +1036,10 @@ SaveInTMP (void) } } -/* --------------------------------------------------------------------------- - * front-end for 'SaveInTMP()' - * just makes sure that the routine is only called once +/*! + * \brief Front-end for 'SaveInTMP()'. + * + * Just makes sure that the routine is only called once. */ static bool dont_save_any_more = false; void @@ -1048,16 +1059,14 @@ DisableEmergencySave (void) dont_save_any_more = true; } -/* ---------------------------------------------------------------------- - * Callback for the autosave - */ - static hidval backup_timer; -/* - * If the backup interval is > 0 then set another timer. Otherwise - * we do nothing and it is up to the GUI to call EnableAutosave() - * after setting Settings.BackupInterval > 0 again. +/*! + * \brief Callback for the autosave. + * + * If the backup interval is > 0 then set another timer. + * Otherwise we do nothing and it is up to the GUI to call + * EnableAutosave() after setting Settings.BackupInterval > 0 again. */ static void backup_cb (hidval data) @@ -1088,10 +1097,12 @@ EnableAutosave (void) x); } -/* --------------------------------------------------------------------------- - * creates backup file. The default is to use the pcb file name with - * a "-" appended (like "foo.pcb-") and if we don't have a pcb file name - * then use the template in BACKUP_NAME +/*! + * \brief Creates backup file. + * + * The default is to use the pcb file name with a "-" appended (like + * "foo.pcb-") and if we don't have a pcb file name then use the + * template in BACKUP_NAME. */ void Backup (void) @@ -1125,11 +1136,13 @@ Backup (void) } #if !defined(HAS_ATEXIT) && !defined(HAS_ON_EXIT) -/* --------------------------------------------------------------------------- - * makes a temporary copy of the data. This is useful for systems which - * doesn't support calling functions on exit. We use this to save the data - * before LEX and YACC functions are called because they are able to abort - * the program. +/*! + * \brief Makes a temporary copy of the data. + * + * This is useful for systems which doesn't support calling functions + * on exit. + * We use this to save the data before LEX and YACC functions are called + * because they are able to abort the program. */ void SaveTMPData (void) @@ -1138,8 +1151,8 @@ SaveTMPData (void) WritePCBFile (TMPFilename); } -/* --------------------------------------------------------------------------- - * removes the temporary copy of the data file +/*! + * \brief Removes the temporary copy of the data file. */ void RemoveTMPData (void) @@ -1148,11 +1161,9 @@ RemoveTMPData (void) } #endif -/* --------------------------------------------------------------------------- - * Parse the directory tree where newlib footprints are found +/*! + * \brief Helper function for ParseLibraryTree. */ - -/* Helper function for ParseLibraryTree */ static char * pcb_basename (char *p) { @@ -1162,9 +1173,11 @@ pcb_basename (char *p) return p; } -/* This is a helper function for ParseLibrary Tree. Given a char *path, - * it finds all newlib footprints in that dir and sticks them into the - * library menu structure named entry. +/*! + * \brief This is a helper function for ParseLibrary Tree. + * + * Given a char *path, it finds all newlib footprints in that dir and + * sticks them into the library menu structure named entry. */ static int LoadNewlibFootprintsFromDir(char *libpath, char *toppath) @@ -1283,7 +1296,10 @@ LoadNewlibFootprintsFromDir(char *libpath, char *toppath) } -/* This function loads the newlib footprints into the Library. +/*! + * \brief Parse the directory tree where newlib footprints are found. + * + * This function loads the newlib footprints into the Library. * It examines all directories pointed to by Settings.LibraryTree. * In each directory specified there, it looks both in that directory, * as well as *one* level down. It calls the subfunction @@ -1402,10 +1418,11 @@ ParseLibraryTree (void) return n_footprints; } -/* --------------------------------------------------------------------------- - * Read contents of the library description file (for M4) - * and then read in M4 libs. Then call a fcn to read the newlib - * footprints. +/*! + * \brief Read contents of the library description file (for M4) + * and then read in M4 libs. + * + * Then call a fcn to read the newlib footprints. */ int ReadLibraryContents (void) @@ -1517,10 +1534,9 @@ ReadLibraryContents (void) #define BLANK(x) ((x) == ' ' || (x) == '\t' || (x) == '\n' \ || (x) == '\0') -/* --------------------------------------------------------------------------- - * Read in a netlist and store it in the netlist menu +/*! + * \brief Read in a netlist and store it in the netlist menu. */ - int ReadNetlist (char *filename) { -- 1.7.3.4