Changeset 569

Show
Ignore:
Timestamp:
09/17/07 07:51:13 (1 year ago)
Author:
takkaria
Message:

Add a doxygen configuration file, doc/ directory, and a makefile target to build docs. Also, convert a few headers along so they produce useful output using doxygen.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/src/Makefile.src

    r545 r569  
    66# 
    77 
    8 VERSION = 3.0.9 
     8VERSION = 3.1.0 
    99 
    10 HDRS = h-basic.h 
    11 INCS = angband.h config.h defines.h externs.h types.h option.h main-gtk.h cairo-utils.h \ 
    12        z-term.h z-rand.h z-type.h z-util.h z-virt.h z-form.h 
     10HEADERS = \ 
     11        angband.h \ 
     12        cairo-utils.h \ 
     13        cmds.h \ 
     14        compress.h \ 
     15        config.h \ 
     16        defines.h \ 
     17        effects.h \ 
     18        externs.h \ 
     19        game-cmd.h \ 
     20        game-event.h \ 
     21        h-basic.h \ 
     22        init.h \ 
     23        maid-x11.h \ 
     24        main-gtk.h \ 
     25        main.h \ 
     26        option.h \ 
     27        randname.h \ 
     28        types.h \ 
     29        ui-event.h \ 
     30        ui.h \ 
     31        ui-menu.h \ 
     32        z-blockfile.h \ 
     33        z-file.h \ 
     34        z-form.h \ 
     35        z-msg.h \ 
     36        z-quark.h \ 
     37        z-rand.h \ 
     38        z-smap.h \ 
     39        z-term.h \ 
     40        z-type.h \ 
     41        z-util.h \ 
     42        z-virt.h 
    1343 
    1444ZFILES = z-file.o z-form.o z-msg.o z-quark.o z-rand.o z-term.o z-type.o \ 

  • trunk/src/Makefile.std

    r545 r569  
    112112install: ../$(EXE) 
    113113 
     114docs: doc/index.html 
    114115 
    115116../$(EXE): $(EXE) 
    …… 
    160161 
    161162# X11 dependencies 
    162 $(X11OBJS) : $(INCS) maid-x11.h main.h 
     163$(X11OBJS) : $(HEADERS) maid-x11.h main.h 
    163164 
    164165# Basic dependencies for main-xxx.c, main.c 
    165 $(MAINOBJS) : main.h $(INCS) 
     166$(MAINOBJS) : main.h $(HEADERS) 
    166167 
    167  
     168# fake Dependency 
     169doc/index.html: $(HEADERS) 
     170        doxygen doc/doxygen.conf 

  • trunk/src/z-blockfile.h

    r515 r569  
    88/*** Constants ***/ 
    99 
    10 /* 
     10/** 
    1111 * For use with bf_open().  Indicate mode of file opening, and when "BF_SAVE" 
    1212 * is set, the file will be marked as a savefile on participating OSes. 
    …… 
    2525 
    2626 
    27 /* 
     27/** 
    2828 * The basic "blockfile" type. 
    2929 * 
    …… 
    4141}; 
    4242 
    43 /* 
     43/** 
    4444 * A block, stored in a blockfile 
    4545 * 
    …… 
    5858}; 
    5959 
    60 /* 
     60/** 
    6161 * A record in a block. 
    6262 */ 
    …… 
    7373/** Opening/saving/closing **/ 
    7474 
    75 /* 
     75/** 
    7676 * Open a new blockfile, with the filename "name" and flags as follows: 
    7777 * 
    …… 
    8686blockfile_t *bf_open(const char *name, u32b flags); 
    8787 
    88 /* 
     88/** 
    8989 * Save all currently held data to the blockfile. 
    9090 * 
    …… 
    9494void bf_save(blockfile_t *bf); 
    9595 
    96 /* 
     96/** 
    9797 * Close a blockfile handle. 
    9898 * 
    …… 
    105105/** Block info **/ 
    106106 
    107 /* 
     107/** 
    108108 * Returns the number of blocks in the blockfile represented by `bf`. 
    109109 */ 
    …… 
    113113/** Block creation **/ 
    114114 
    115 /* 
     115/** 
    116116 * Create a new block in the blockfile `bf` with name `name`. 
    117117 * 
    …… 
    126126/** Finding blocks **/ 
    127127 
    128 /* 
     128/** 
    129129 * Finds a block in the blockfile `bf` with the name `name`. 
    130130 * 
    …… 
    134134block_t *bf_findblock(blockfile_t *bf, const char *name); 
    135135 
    136 /* 
     136/** 
    137137 * Return the next block in the blockfile `bf`. 
    138138 * 
    …… 
    145145block_t *bf_nextblock(blockfile_t *bf); 
    146146 
    147 /* 
     147/** 
    148148 * Reset the current block in the blockfile `bf`.  This is only useful if, 
    149149 * having once iterated through some blocks in the file, you want to return to 
    …… 
    153153 
    154154 
    155 /* 
     155/** 
    156156 * Calls the provided function for each block in the file `bf`, in the order in 
    157157 * which they were written. 
    …… 
    162162/** Block information **/ 
    163163 
    164 /* 
     164/** 
    165165 * Returns the name of block `block`. 
    166166 */ 
    167167const char *bf_name(block_t *block); 
    168168 
    169 /* 
     169/** 
    170170 * Returns the size of block `block`. 
    171171 */ 
    172172u32b bf_blocksize(block_t *block); 
    173173 
    174 /* 
     174/** 
    175175 * Returns the number of records stored within the block `block`. 
    176176 */ 
    …… 
    181181/** Record creation and reading **/ 
    182182 
    183 /* 
     183/** 
    184184 * Create a new record in the block `block`, with data `data` of length `len`. 
    185185 * 
    …… 
    189189void bf_createrecord(block_t *block, void *data, u32b len); 
    190190 
    191 /* 
     191/** 
    192192 * Return the data of the next record in the block `block`, and place the 
    193193 * length of this data in *`len`. 
    …… 
    201201const void *bf_nextrecord(block_t *block, u32b *len); 
    202202 
    203 /* 
     203/** 
    204204 * Reset the current record in the block `block`.  This is only useful if, 
    205205 * having once iterated through some records in the block, you want to return 
    …… 
    208208void bf_rewindrecord(block_t *block); 
    209209 
    210 /* 
     210/** 
    211211 * Calls the supplied `fn` to iterate over each record in the block `block`. 
    212212 */ 

  • trunk/src/z-file.h

    r536 r569  
    66/*** Permissions code ***/ 
    77 
    8 /*  
     8/** 
    99 * Player's user ID and group ID, respectively. 
    1010 * 
    …… 
    1414extern int player_egid; 
    1515 
    16 /* 
     16/** 
    1717 * Drop or grab privileges. 
    1818 * 
    …… 
    3232/*** Path building code ***/ 
    3333 
    34 /* 
     34/** 
    3535 * Concatenates "leaf" onto the end of "base", using system-specific path 
    3636 * separators, and places the result in buf[], truncated to "len" bytes. 
    …… 
    4444/*** Byte-flipping functions ***/ 
    4545 
    46 /* 
     46/** 
    4747 * "Flip" the bits of the integer specified in `arg` to make them big-endian. 
    4848 * Useful when writing to files intended to be portable across systems. 
    …… 
    6060/** Data types **/ 
    6161 
    62 /* 
     62/** 
    6363 * An opaque file handle for Angband file handling. 
    6464 */ 
    6565typedef struct ang_file ang_file; 
    6666 
    67 /* 
     67/** 
    6868 * Specifies what kind of access is required to a file.  See file_open(). 
    6969 */ 
    …… 
    7575} file_mode; 
    7676 
    77 /* 
    78  * Specified what kind of thing a file is, when writing.  See file_open(). 
     77/** 
     78 * Specifies what kind of thing a file is, when writing.  See file_open(). 
    7979 */ 
    8080typedef enum 
    …… 
    8989/** Utility functions **/ 
    9090 
    91 /* 
     91/** 
    9292 * Returns TRUE if `fname` exists (and is a file), FALSE otherwise. 
    9393 */ 
    9494bool file_exists(const char *fname); 
    9595 
    96 /* 
     96/** 
    9797 * Tries to delete `fname`. 
    9898 * 
    …… 
    101101bool file_delete(const char *fname); 
    102102 
    103 /* 
     103/** 
    104104 * Moves the file `fname` to `newname`. 
    105105 * 
    …… 
    108108bool file_move(const char *fname, const char *newname); 
    109109 
    110 /* 
     110/** 
    111111 * Returns TRUE if the file `first` is newer than `second`. 
    112112 */ 
    …… 
    116116/** File handle creation **/ 
    117117 
    118 /* 
     118/** 
    119119 * Open file `buf`, returning a a file handling representing that file. 
    120120 * 
    …… 
    133133ang_file *file_open(const char *buf, file_mode mode, file_type ftype); 
    134134 
    135 /* 
     135/** 
    136136 * Attempt to close the file handle `f`. 
    137137 * 
    …… 
    143143/** File locking **/ 
    144144 
    145 /* 
     145/** 
    146146 * Lock or unlock the file represented by `f` for writing. 
    147147 * If the file is not open for writing, this call will fail. 
    …… 
    155155/** Line-based IO **/ 
    156156 
    157 /* 
     157/** 
    158158 * Get a line of text from the file represented by `f`, placing it into `buf` 
    159159 * to a maximum length of `n`. 
    …… 
    166166bool file_getl(ang_file *f, char *buf, size_t n); 
    167167 
    168 /* 
     168/** 
    169169 * Write the string pointed to by `buf` to the file represented by `f`. 
    170170 * 
    …… 
    173173bool file_put(ang_file *f, const char *buf); 
    174174 
    175 /* 
     175/** 
    176176 * Format (using strnfmt) the given args, and then call file_put(). 
    177177 */ 
    …… 
    181181/** Byte-based IO */ 
    182182 
    183 /* 
     183/** 
    184184 * Seek to position `pos` in the file represented by `f`. 
    185185 * 
    …… 
    188188bool file_seek(ang_file *f, u32b pos); 
    189189 
    190 /* 
     190/** 
    191191 * Reads `n` bytes from the file represented by `f` into the buffer `buf`. 
    192192 * Do not mix with calls to file_readc(). 
    …… 
    196196size_t file_read(ang_file *f, char *buf, size_t n); 
    197197 
    198 /* 
     198/** 
    199199 * Write the first `n` bytes following the pointer `buf` to the file represented 
    200200 * by `f`.  Do not mix with calls to file_writec(). 
    …… 
    204204bool file_write(ang_file *f, const char *buf, size_t n); 
    205205 
    206 /* 
     206/** 
    207207 * Read a byte from the file represented by `f` and place it at the location 
    208208 * specified by 'b'. 
    …… 
    212212bool file_readc(ang_file *f, byte *b); 
    213213 
    214 /* 
     214/** 
    215215 * Write the byte `b` to the file represented by `f`. 
    216216 * 
    …… 
    223223/*** Directory code ***/ 
    224224 
    225 /* 
     225/** 
    226226 * An opaque file handle for Angband directory handling. 
    227227 */ 
    …… 
    229229 
    230230 
    231 /* 
     231/** 
    232232 * Opens a directory handle. 
    233233 * 
    …… 
    239239ang_dir *my_dopen(const char *dirname); 
    240240 
    241 /* 
     241/** 
    242242 * Reads a directory entry. 
    243243 * 
    …… 
    250250bool my_dread(ang_dir *dir, char *fname, size_t len); 
    251251 
    252 /* 
     252/** 
    253253 * Close a directory handle. 
    254254 */ 

  • trunk/src/z-form.h

    r155 r569  
    1 /* File z-form.h */ 
    2  
    3 /* 
    4  * Copyright (c) 1997 Ben Harrison 
    5  * 
    6  * This software may be copied and distributed for educational, research, 
    7  * and not for profit purposes provided that this copyright and statement 
    8  * are included in all such copies. 
    9  */ 
    10  
    111#ifndef INCLUDED_Z_FORM_H 
    122#define INCLUDED_Z_FORM_H 

  • trunk/src/z-msg.h

    r514 r569  
    171171/** Initialisation/exit **/ 
    172172 
    173 /* 
     173/** 
    174174 * Initialise the messages package.  Should be called before using any other 
    175175 * functions in the package. 
    …… 
    177177errr messages_init(void); 
    178178 
    179 /* 
     179/** 
    180180 * Free the message package. 
    181181 */ 
    …… 
    185185/** General info **/ 
    186186 
    187 /* 
     187/** 
    188188 * Return the current number of messages stored. 
    189189 */ 
    …… 
    193193/** Individual message handling **/ 
    194194 
    195 /* 
     195/** 
    196196 * Save a new message into the memory buffer, with text `str` and type `type`. 
    197197 * The type should be one of the MSG_ constants defined above. 
    …… 
    204204 
    205205 
    206 /* 
     206/** 
    207207 * Returns the text of the message of age `age`.  The age of the most recently 
    208208 * saved message is 0, the one before that is of age 1, etc. 
    …… 
    213213const char *message_str(u16b age); 
    214214 
    215 /* 
     215/** 
    216216 * Returns the number of times the message of age `age` was saved. The age of 
    217217 * the most recently saved message is 0, the one before that is of age 1, etc. 
    …… 
    223223u16b message_count(u16b age); 
    224224 
    225 /* 
     225/** 
    226226 * Returns the type of the message of age `age`.  The age of the most recently 
    227227 * saved message is 0, the one before that is of age 1, etc. 
    …… 
    231231u16b message_type(u16b age); 
    232232 
    233 /* 
     233/** 
    234234 * Returns the display colour of the message memorised `age` messages ago. 
    235235 * (i.e. age = 0 represents the last memorised message, age = 1 is the one 
    …… 
    241241/** Message type changes **/ 
    242242 
    243 /* 
     243/** 
    244244 * Returns the colour for the message type `type`. 
    245245 */  
    246246byte message_type_color(u16b type); 
    247247 
    248 /* 
     248/** 
    249249 * Defines the color `color` for the message type `type`. 
    250250 */ 

  • trunk/src/z-rand.h

    r461 r569  
    1 /* File: z-rand.h */ 
    2  
    3 /* 
    4  * Copyright (c) 1997 Ben Harrison, and others 
    5  * 
    6  * This software may be copied and distributed for educational, research, 
    7  * and not for profit purposes provided that this copyright and statement 
    8  * are included in all such copies.  Other copyrights may also apply. 
    9  */ 
    10  
    111#ifndef INCLUDED_Z_RAND_H 
    122#define INCLUDED_Z_RAND_H 
    …… 
    155 
    166 
     7/**** Constants ****/ 
    178 
    18 /**** Available constants ****/ 
    19  
    20  
    21 /* 
     9/** 
    2210 * The "degree" of the "complex" Random Number Generator. 
    2311 * This value is hard-coded at 63 for a wide variety of reasons. 
    …… 
    2715 
    2816 
    29  
    3017/**** Available macros ****/ 
    3118 
    32  
    33 /* 
    34  * Generates a random long integer X where O<=X<M. 
     19/** 
     20 * Generates a random signed long integer X where "0 <= X < M" holds. 
     21 * 
    3522 * The integer X falls along a uniform distribution. 
    36  * For example, if M is 100, you get "percentile dice" 
    3723 */ 
    38 #define rand_int(M) \ 
    39         ((s32b)(Rand_div(M))) 
     24#define rand_int(M)             ((s32b) Rand_div(M)) 
    4025 
    4126 
    42 /* 
    43  * Generates a random long integer X where 1<=X<=M. 
     27/** 
     28 * Generates a random signed long integer X where "1 <= X <= M" holds. 
    4429 * 
    45  * Note that the behaviour for M < 1 is undefined. 
     30 * The integer X falls along a uniform distribution. 
    4631 */ 
    47 #define randint(M) \ 
    48         (rand_int(M) + 1) 
    49  
    50 /* 
    51  * Generates a random long integer X where 1<=X<=M. 
    52  * 
    53  * Note that the behaviour for M < 1 is undefined. 
    54  */ 
    55 #define rand_die(M) \ 
    56         (rand_int(M) + 1) 
     32#define randint(M)              ((s32b) Rand_div(M) + 1) 
     33#define rand_die(M)             (rand_int(M) + 1) 
    5734 
    5835 
    59 /* 
    60  * Generates a random long integer X where A<=X<=B 
     36/** 
     37 * Generates a random signed long integer X where "A <= X <= B" 
     38 * Note that "rand_range(0, N-1)" == "rand_int(N)" 
     39 * 
    6140 * The integer X falls along a uniform distribution. 
    62  * Note: rand_range(0,N-1) == rand_int(N) 
    6341 */ 
    64 #define rand_range(A,B) \ 
    65         ((A) + (rand_int(1+(B)-(A)))) 
     42#define rand_range(A,B)         ((A) + (rand_int(1+(B)-(A)))) 
    6643 
    67 /* 
    68  * Generate a random long integer X where A-D<=X<=A+D 
     44 
     45/** 
     46 * Generate a random signed long integer X where "A-D <= X <= A+D" holds. 
     47 * Note that "rand_spread(A, D)" == "rand_range(A-D, A+D)" 
     48 * 
    6949 * The integer X falls along a uniform distribution. 
    70  * Note: rand_spread(A,D) == rand_range(A-D,A+D) 
    7150 */ 
    72 #define rand_spread(A,D) \ 
    73         ((A) + (rand_int(1+(D)+(D))) - (D)) 
     51#define rand_spread(A,D)        ((A) + (rand_int(1+(D)+(D))) - (D)) 
    7452 
    7553 
    …… 
    7755/**** Available Variables ****/ 
    7856 
    79  
     57/** 
     58 * Do not tweak these variables. 
     59 */ 
    8060extern bool Rand_quick; 
    8161extern u32b Rand_value; 
    …… 
    8666/**** Available Functions ****/ 
    8767 
     68/** 
     69 * Initialise the RNG state with the given seed. 
     70 */ 
     71void Rand_state_init(u32b seed); 
    8872 
    89 extern void Rand_state_init(u32b seed); 
    90 extern u32b Rand_div(u32b m); 
    91 extern s16b Rand_normal(int mean, int stand); 
    92 extern u32b Rand_simple(u32b m); 
     73/** 
     74 * Generates a random unsigned long integer X where "0 <= X < M" holds. 
     75 * 
     76 * The integer X falls along a uniform distribution. 
     77 */ 
     78u32b Rand_div(u32b m); 
    9379 
    94 extern int damroll(int num, int sides); 
     80/** 
     81 * Generate a signed random integer within `stand` standard deviations of 
     82 * `mean`, following a normal distribution. 
     83 */ 
     84s16b Rand_normal(int mean, int stand); 
     85 
     86/** 
     87 * Generate a semi-random number from 0 to m-1, in a way that doesn't affect 
     88 * gameplay.  This is intended for use by external program parts like the 
     89 * main-*.c files. 
     90 */ 
     91u32b Rand_simple(u32b m); 
     92 
     93/** 
     94 * Emulate a number `num` of dice rolls of dice with `sides` sides. 
     95 */ 
     96int damroll(int num, int sides); 
    9597 
    9698 

  • trunk/src/z-util.h

    r337 r569  
    1 /* File z-util.h */ 
    2  
    3 /* 
    4  * Copyright (c) 1997 Ben Harrison 
    5  * 
    6  * This software may be copied and distributed for educational, research, 
    7  * and not for profit purposes provided that this copyright and statement 
    8  * are included in all such copies. 
    9  */ 
    10  
    111#ifndef INCLUDED_Z_UTIL_H 
    122#define INCLUDED_Z_UTIL_H 
    …… 
    155 
    166 
    17 /* 
    18  * Extremely basic stuff, like global temp and constant variables. 
    19  * Also, some very useful low level functions, such as "streq()". 
    20  * All variables and functions in this file are "addressable". 
    21  */ 
    22  
    23  
    247/**** Available variables ****/ 
    258 
    26 /* A cptr to the name of the program */ 
    27 extern cptr argv0; 
     9/** 
     10 * The name of the program. 
     11 */ 
     12extern const char *argv0; 
    2813 
    2914 
    …… 
    3520/**** Available Functions ****/ 
    3621 
    37 /* Case insensitive comparison between two strings */ 
     22/** 
     23 * Case insensitive comparison between two strings 
     24 */ 
    3825extern int my_stricmp(const char *s1, const char *s2); 
     26 
     27/** 
     28 * Case insensitive comparison between two strings, up to n characters long. 
     29 */ 
    3930extern int my_strnicmp(cptr a, cptr b, int n); 
    4031 
    41 /* Case-insensitive strstr */ 
     32/** 
     33 * Case-insensitive strstr 
     34 */ 
    4235extern char *my_stristr(const char *string, const char *pattern); 
    4336 
    44 /* Copy a string */ 
     37/** 
     38 * Copy up to 'bufsize'-1 characters from 'src' to 'buf' and NULL-terminate 
     39 * the result.  The 'buf' and 'src' strings may not overlap. 
     40 * 
     41 * Returns: strlen(src).  This makes checking for truncation 
     42 * easy.  Example: 
     43 *   if (my_strcpy(buf, src, sizeof(buf)) >= sizeof(buf)) ...; 
     44 * 
     45 * This function should be equivalent to the strlcpy() function in BSD. 
     46 */ 
    4547extern size_t my_strcpy(char *buf, const char *src, size_t bufsize); 
    4648 
    47 /* Concatenate two strings */ 
     49/** 
     50 * Try to append a string to an existing NULL-terminated string, never writing 
     51 * more characters into the buffer than indicated by 'bufsize', and 
     52 * NULL-terminating the buffer.  The 'buf' and 'src' strings may not overlap. 
     53 * 
     54 * my_strcat() returns strlen(buf) + strlen(src).  This makes checking for 
     55 * truncation easy.  Example: 
     56 *   if (my_strcat(buf, src, sizeof(buf)) >= sizeof(buf)) ...; 
     57 * 
     58 * This function should be equivalent to the strlcat() function in BSD. 
     59 */ 
    4860extern size_t my_strcat(char *buf, const char *src, size_t bufsize); 
    4961