/*
* Initialize thread package.
- * CTX points to a thread context variable; see empth_create().
- * FLAGS request optional features.
+ * @ctx points to a thread context variable; see empth_create().
+ * @flags request optional features.
* Should return 0 on success, -1 on error, but currently always
* returns 0.
*/
/*
* Create a new thread.
- * ENTRY is the entry point. It will be called with argument UD.
+ * @entry is the entry point. It will be called with argument @ud.
* If it returns, the thread terminates as if it called empth_exit().
- * Thread stack is at least SIZE bytes.
- * FLAGS should be the same as were passed to empth_init(), or zero.
- * NAME is the thread's name, it is used for logging and debugging.
- * UD is the value to pass to ENTRY. It is also assigned to the
+ * Thread stack is at least @size bytes.
+ * @flags should be the same as were passed to empth_init(), or zero.
+ * @name is the thread's name, it is used for logging and debugging.
+ * @ud is the value to pass to @entry. It is also assigned to the
* context variable defined with empth_init() whenever the thread gets
* scheduled.
* Yield the processor.
empth_t *empth_self(void);
/*
- * Return THREAD's name.
+ * Return @thread's name.
*/
char *empth_name(empth_t *thread);
/*
- * Set THREAD's name to NAME.
+ * Set @thread's name to @name.
*/
void empth_set_name(empth_t *thread, char *name);
void empth_yield(void);
/*
- * Put current thread to sleep until file descriptor FD is ready for I/O.
- * If FLAGS & EMPTH_FD_READ, wake up if FD is ready for input.
- * If FLAGS & EMPTH_FD_WRITE, wake up if FD is ready for output.
+ * Put current thread to sleep until file descriptor @fd is ready for I/O.
+ * If @flags & EMPTH_FD_READ, wake up if @fd is ready for input.
+ * If @flags & EMPTH_FD_WRITE, wake up if @fd is ready for output.
* At most one thread may sleep on the same file descriptor.
- * TIMEOUT, if non-null, limits the sleep time.
- * Return one when the FD is ready, zero on timeout or early wakeup by
+ * @timeout, if non-null, limits the sleep time.
+ * Return one when the @fd is ready, zero on timeout or early wakeup by
* empth_wakeup(), -1 on error with errno set.
- * Note: Currently, Empire sleeps only on network I/O, i.e. FD is a
+ * Note: Currently, Empire sleeps only on network I/O, i.e. @fd is a
* socket. Implementations should not rely on that.
*/
int empth_select(int fd, int flags, struct timeval *timeout);
/*
- * Awaken THREAD if it is sleeping in empth_select() or empth_sleep().
+ * Awaken @thread if it is sleeping in empth_select() or empth_sleep().
* This does not awaken threads sleeping in other functions.
* Does not yield the processor.
*/
void empth_wakeup(empth_t *thread);
/*
- * Put current thread to sleep until the time is UNTIL.
+ * Put current thread to sleep until the time is @until.
* Return 0 if it slept until that time.
* Return -1 if woken up early, by empth_wakeup().
*/
/*
* Create a read-write lock.
- * NAME is its name, it is used for debugging.
+ * @name is its name, it is used for debugging.
* Return the read-write lock, or NULL on error.
*/
empth_rwlock_t *empth_rwlock_create(char *name);
/*
- * Destroy RWLOCK.
+ * Destroy @rwlock.
*/
void empth_rwlock_destroy(empth_rwlock_t *rwlock);
/*
- * Lock RWLOCK for writing.
+ * Lock @rwlock for writing.
* A read-write lock can be locked for writing only when it is
* unlocked. If this is not the case, put the current thread to sleep
* until it is.
void empth_rwlock_wrlock(empth_rwlock_t *rwlock);
/*
- * Lock RWLOCK for reading.
+ * Lock @rwlock for reading.
* A read-write lock can be locked for reading only when it is not
* locked for writing, and no other thread is attempting to lock it
* for writing. If this is not the case, put the current thread to
void empth_rwlock_rdlock(empth_rwlock_t *rwlock);
/*
- * Unlock read-write lock RWLOCK.
- * The current thread must hold RWLOCK.
+ * Unlock read-write lock @rwlock.
+ * The current thread must hold @rwlock.
* Wake up threads that can now lock it.
*/
void empth_rwlock_unlock(empth_rwlock_t *rwlock);
#include "types.h"
/*
- * Width of the body of a map using PERSEC characters per sector.
+ * Width of the body of a map using @persec characters per sector.
*
* One row shows WORLD_X/2 sectors, separated by one space. Requires
- * WORLD_X/2 * (PERSEC+1) - 1 characters.
+ * WORLD_X/2 * (@persec+1) - 1 characters.
*
* Every other row is indented so that the center of the first sector
* is aligned with the space separating the first two sectors in the
- * adjacent rows. For odd PERSEC, that's (PERSEC+1)/2 additional
- * characters. For even PERSEC, it's either PERSEC/2 or PERSEC/2 + 1,
+ * adjacent rows. For odd @persec, that's (@persec+1)/2 additional
+ * characters. For even @persec, it's either @persec/2 or @persec/2 + 1,
* depending on whether we align the character left or right of the
* center with the space (the map will look rather odd either way).
*
#define days(x) (60*60*24*(x))
/*
- * If EXPR is true, an internal error occured.
- * Return EXPR != 0.
+ * If @expr is true, an internal error occured.
+ * Return @expr != 0.
* Usage: if (CANT_HAPPEN(...)) <recovery code>;
*/
#define CANT_HAPPEN(expr) ((expr) ? oops(#expr, __FILE__, __LINE__), 1 : 0)
* Value, possibly symbolic
*
* If type is NSC_NOTYPE, it's an error value.
- * If category is NSC_VAL, the value is in val_as, and the type is a
+ * If category is NSC_VAL, the value is in @val_as, and the type is a
* promoted type.
* If category is NSC_OFF, the value is in a context object, and
- * val_as.sym specifies how to get it, as follows.
+ * @val_as.sym specifies how to get it, as follows.
* If sym.get is null, and type is NSC_STRINGY, the value is a string
* stored in sym.len characters starting at sym.offs in the context
* object. sym.idx must be zero. Ugly wart: if sym.len is one, the
};
/*
- * Symbol binding: associate NAME with VALUE.
+ * Symbol binding: associate @name with @value.
*/
struct symbol {
int value;
* Selector descriptor
*
* A selector describes an attribute of some context object.
- * A selector with ca_type NSC_NOTYPE is invalid.
- * If ca_get is null, the selector describes a datum of type ca_type
- * at offset ca_offs in the context object.
+ * A selector with @ca_type NSC_NOTYPE is invalid.
+ * If @ca_get is null, the selector describes a datum of type @ca_type
+ * at offset @ca_offs in the context object.
* A datum of type NSC_STRINGY is a string stored in an array of
- * ca_len characters. Ugly wart: if ca_len is one, the terminating
+ * @ca_len characters. Ugly wart: if @ca_len is one, the terminating
* null character may be omitted.
* A datum of any other type is either a scalar of that type (if
- * ca_len is zero), or an array of ca_len elements of that type.
- * If ca_get is not null, the selector is virtual. Values can be
- * obtained by calling ca_get(VAL, NP, CTXO), where VAL has been
+ * @ca_len is zero), or an array of @ca_len elements of that type.
+ * If @ca_get is not null, the selector is virtual. Values can be
+ * obtained by calling @ca_get(VAL, NP, CTXO), where VAL has been
* initialized from the selector and an index by nstr_mksymval(),
* NP points to the country to use for coordinate translation and
* access control (null for none), and CTXO is the context object.
* elements, indexed by country number, and the context object must be
* EF_NATION. Array elements are masked for contact when opt_HIDDEN
* is on.
- * If ca_table is not EF_BAD, the datum refers to that Empire table;
- * ca_type must be an integer type. If flag NSC_BITS is set, the
+ * If @ca_table is not EF_BAD, the datum refers to that Empire table;
+ * @ca_type must be an integer type. If flag NSC_BITS is set, the
* datum consists of flag bits, and the referred table must be a
* symbol table defining those bits.
*/
/*
* Initialize empty line buffer.
- * Not necessary if *LBUF is already zeroed.
+ * Not necessary if *@lbuf is already zeroed.
*/
void
lbuf_init(struct lbuf *lbuf)
}
/*
- * Is LBUF full (i.e. we got the newline)?
+ * Is @lbuf full (i.e. we got the newline)?
*/
int
lbuf_full(struct lbuf *lbuf)
}
/*
- * Append CH to the line buffered in LBUF.
- * LBUF must not be full.
- * If CH is a newline, the buffer is now full. Return the line
+ * Append @ch to the line buffered in @lbuf.
+ * @lbuf must not be full.
+ * If @ch is a newline, the buffer is now full. Return the line
* length, including the newline.
* Else return 0 if there was space, and -1 if not.
*/
static volatile sig_atomic_t send_intr; /* need to send INTR_COOKIE */
/*
- * Receive and process server output from SOCK.
+ * Receive and process server output from @sock.
* Return number of characters received on success, -1 on error.
*/
static int
}
/*
- * Receive command input from FD into INBUF.
+ * Receive command input from @fd into @inbuf.
* Return 1 on receipt of input, zero on EOF, -1 on error.
*/
static int
}
/*
- * Play on SOCK.
+ * Play on @sock.
* The session must be in the playing phase.
* Return 0 when the session ended, -1 on error.
*/
/*
* Peek at ring buffer contents.
- * N must be between -RING_SIZE-1 and RING_SIZE.
- * If N>=0, peek at the (N+1)-th byte to be gotten.
- * If N<0, peek at the -N-th byte that has been put in.
+ * @n must be between -RING_SIZE-1 and RING_SIZE.
+ * If @n>=0, peek at the (@n+1)-th byte to be gotten.
+ * If @n<0, peek at the -@n-th byte that has been put in.
* Return the byte as unsigned char coverted to int, or EOF if there
* aren't that many bytes in the ring buffer.
*/
}
/*
- * Attempt to put byte C into the ring buffer.
- * Return EOF when the buffer is full, else C.
+ * Attempt to put byte @c into the ring buffer.
+ * Return EOF when the buffer is full, else @c.
*/
int
ring_putc(struct ring *r, unsigned char c)
}
/*
- * Attempt to put SZ bytes from BUF into the ring buffer.
+ * Attempt to put @sz bytes from @buf into the ring buffer.
* Return space left in ring buffer when it fits, else don't change
* the ring buffer and return how much space is missing times -1.
*/
}
/*
- * Fill ring buffer from file referred by file descriptor FD.
+ * Fill ring buffer from file referred by file descriptor @fd.
* If ring buffer is already full, do nothing and return 0.
* Else attempt to read as many bytes as space permits, with readv(),
* and return its value.
}
/*
- * Drain ring buffer to file referred by file descriptor FD.
+ * Drain ring buffer to file referred by file descriptor @fd.
* If ring buffer is already empty, do nothing and return 0.
* Else attempt to write complete contents with writev(), and return
* its value.
static size_t saved_bytes;
/*
- * Remember line of input INP for a while.
+ * Remember line of input @inp for a while.
* It must end with a newline.
* Return value is suitable for forget_input(): it makes it forget all
* input up to and including this line.
}
/*
- * Can you still remember a line of input that ends with TAIL?
+ * Can you still remember a line of input that ends with @tail?
* It must end with a newline.
- * Return non-zero iff TAIL can be remembered.
+ * Return non-zero iff @tail can be remembered.
* Passing that value to forget_input() will forget all input up to
* and including this line.
*/
}
/*
- * Forget remembered input up to SEEN.
- * SEEN should be obtained from save_input() or seen_input().
+ * Forget remembered input up to @seen.
+ * @seen should be obtained from save_input() or seen_input().
*/
void
forget_input(size_t seen)
}
/*
- * Send flash message(s) from US to TO.
- * Null TO broadcasts to all.
- * MESSAGE is UTF-8. If it is null, prompt for messages interactively.
+ * Send flash message(s) from @us to @to.
+ * Null @to broadcasts to all.
+ * @message is UTF-8. If it is null, prompt for messages interactively.
* Return RET_OK.
*/
static int
}
/*
- * Send flash message MESSAGE from US to TO.
- * MESSAGE is UTF-8.
- * Null TO broadcasts to all.
- * A header identifying US is prepended to the message. It is more
- * verbose if VERBOSE.
+ * Send flash message @message from @us to @to.
+ * @message is UTF-8.
+ * Null @to broadcasts to all.
+ * A header identifying @us is prepended to the message. It is more
+ * verbose if @verbose.
*/
static int
sendmessage(struct natstr *to, char *message, int verbose)
}
/*
- * Launch anti-sat weapon PP.
+ * Launch anti-sat weapon @pp.
* Return RET_OK if launched (even when missile explodes),
* else RET_SYN or RET_FAIL.
*/
}
/*
- * Launch missile PP.
+ * Launch missile @pp.
* Return RET_OK if launched (even when missile explodes),
* else RET_SYN or RET_FAIL.
*/
}
/*
- * Print first telegram in file FNAME.
+ * Print first telegram in file @fname.
*/
int
show_first_tel(char *fname)
#include "xdump.h"
/*
- * Is object P of type TYPE visible to the player?
+ * Is object @p of type @type visible to the player?
* TODO: Fold this into interators.
*/
static int
}
/*
- * Dump meta-data for items of type TYPE to XD.
- * Return RET_SYN when TYPE doesn't have meta-data, else RET_OK.
+ * Dump meta-data for items of type @type to @xd.
+ * Return RET_SYN when @type doesn't have meta-data, else RET_OK.
*/
static int
xdmeta(struct xdstr *xd, int type)
}
/*
- * Dump items of type TYPE selected by ARG to XD.
+ * Dump items of type @type selected by @arg to @xd.
* Return RET_OK on success, RET_SYN on error.
*/
static int
* Ken Stevens, Steve McClure, Markus Armbruster
*
* Empire is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
+ * it under the terms of the @GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ * but @WITHOUT @ANY @WARRANTY; without even the implied warranty of
+ * @MERCHANTABILITY or @FITNESS @FOR A @PARTICULAR @PURPOSE. See the
+ * @GNU General Public License for more details.
*
- * You should have received a copy of the GNU General Public License
+ * You should have received a copy of the @GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* ---
*
- * See files README, COPYING and CREDITS in the root of the source
+ * See files @README, @COPYING and @CREDITS in the root of the source
* tree for related information and legal notices. It is expected
* that future projects/authors will amend these files as needed.
*
#include "sect.h"
/*
- * Return BTUs produced by CAP in ETU ETUs.
+ * Return BTUs produced by @cap in @etu ETUs.
*/
static int
accrued_btus(struct sctstr *cap, int etu)
}
/*
- * Grant nation NP the BTUs produced by its capital in ETU ETUs.
+ * Grant nation @np the BTUs produced by its capital in @etu ETUs.
* Return whether it has a capital.
*/
int
static int nclink[EF_NUKE + 1];
/*
- * Return pointer to CL's cargo list head for file type TYPE.
+ * Return pointer to @cl's cargo list head for file type @type.
*/
static int *
clink_headp(struct clink *cl, int type)
}
/*
- * Initialize cargo list link CL to empty.
+ * Initialize cargo list link @cl to empty.
*/
static void
clink_init(struct clink *cl)
}
/*
- * Check whether *UIDP is a valid uid for file type TYPE.
+ * Check whether *@uidp is a valid uid for file type @type.
*/
static void
clink_check1(int *uidp, int type)
}
/*
- * Check validity of cargo lists for file type TYPE.
+ * Check validity of cargo lists for file type @type.
*/
static void
clink_check(int type)
}
/*
- * Add to CL's cargo list for type TYPE the uid UID.
- * UID must not be on any cargo list already.
+ * Add to @cl's cargo list for type @type the uid @uid.
+ * @uid must not be on any cargo list already.
*/
static void
clink_add(struct clink *cl, int type, int uid)
}
/*
- * Remove from CL's cargo list for type TYPE the uid UID.
- * UID must be on that cargo list.
+ * Remove from @cl's cargo list for type @type the uid @uid.
+ * @uid must be on that cargo list.
*/
static void
clink_rem(struct clink *cl, int type, int uid)
}
/*
- * Update cargo lists for a change of CARGO's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @cargo's carrier.
+ * Carrier is of type @type, and changes from uid @old to @new.
* Negative uids mean no carrier.
*/
void
}
/*
- * Update cargo lists for a change of PP's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @pp's carrier.
+ * Carrier is of type @type, and changes from uid @old to @new.
* Negative uids mean no carrier.
*/
void
}
/*
- * Update cargo lists for a change of LP's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @lp's carrier.
+ * Carrier is of type @type, and changes from uid @old to @new.
* Negative uids mean no carrier.
*/
void
}
/*
- * Update cargo lists for a change of NP's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @np's carrier.
+ * Carrier is of type @type, and changes from uid @old to @new.
* Negative uids mean no carrier.
*/
void
}
/*
- * Resize clink[TYPE] to match ef_nelem(TYPE).
+ * Resize clink[@type] to match ef_nelem(@type).
* Return 0 on success, -1 on error.
* This is the struct empfile onresize callback for units.
*/
}
/*
- * Find first unit on a carrier's cargo list for file type CARGO_TYPE.
- * Search carrier UID of type TYPE.
+ * Find first unit on a carrier's cargo list for file type @cargo_type.
+ * Search carrier @uid of type @type.
* Return first unit's uid, or -1 if the carrier isn't carrying such
* units.
*/
}
/*
- * Find the next unit on a cargo list for file type CARGO_TYPE.
- * Get the unit after CARGO_UID.
+ * Find the next unit on a cargo list for file type @cargo_type.
+ * Get the unit after @cargo_uid.
* Return its uid, or -1 if there are no more on this list.
*/
int
}
/*
- * If SP carries planes, return the uid of the first one, else -1.
+ * If @sp carries planes, return the uid of the first one, else -1.
*/
int
pln_first_on_ship(struct shpstr *sp)
}
/*
- * If LP carries planes, return the uid of the first one, else -1.
+ * If @lp carries planes, return the uid of the first one, else -1.
*/
int
pln_first_on_land(struct lndstr *lp)
}
/*
- * Find the next plane on the same carrier as plane#UID.
+ * Find the next plane on the same carrier as plane#@uid.
* Return its uid, or -1 if there are no more.
*/
int
}
/*
- * If SP carries land units, return the uid of the first one, else -1.
+ * If @sp carries land units, return the uid of the first one, else -1.
*/
int
lnd_first_on_ship(struct shpstr *sp)
}
/*
- * If SP carries land units, return the uid of the first one, else -1.
+ * If @sp carries land units, return the uid of the first one, else -1.
*/
int
lnd_first_on_land(struct lndstr *lp)
}
/*
- * Find the next land unit on the same carrier as land#UID.
+ * Find the next land unit on the same carrier as land#@uid.
* Return its uid, or -1 if there are no more.
*/
int
}
/*
- * If PP carries a nuke, return its uid, else -1.
+ * If @pp carries a nuke, return its uid, else -1.
*/
int
nuk_on_plane(struct plnstr *pp)
}
/*
- * Return length of a carrier's cargo list for file type CARGO_TYPE.
+ * Return length of a carrier's cargo list for file type @cargo_type.
*/
int
unit_cargo_count(int type, int uid, int cargo_type)
}
/*
- * Return number of land units loaded on SP.
+ * Return number of land units loaded on @sp.
*/
int
shp_nland(struct shpstr *sp)
}
/*
- * Return number of land units loaded on LP.
+ * Return number of land units loaded on @lp.
*/
int
lnd_nland(struct lndstr *lp)
#include "prototypes.h"
/*
- * Search for a country matching CNTRY, return its number.
+ * Search for a country matching @cntry, return its number.
* Return M_NOTFOUND if no such country exists, M_NOTUNIQUE if there
* are several.
*/
}
/*
- * Read configuration table file FNAME.
+ * Read configuration table file @fname.
* Return 0 on success, -1 on error.
*/
static int
/*
* Verify game state is sane.
* Correct minor problems, but write corrections to backing files only
- * if MAY_PUT is non-zero.
+ * if @may_put is non-zero.
* Return -1 if uncorrected problems remain, else 0.
*/
int
static unsigned ef_generation;
/*
- * Open the file-backed table TYPE (EF_SECTOR, ...).
- * HOW are flags to control operation. Naturally, immutable flags are
+ * Open the file-backed table @type (EF_SECTOR, ...).
+ * @how are flags to control operation. Naturally, immutable flags are
* not permitted.
* The table must not be already open.
* Return non-zero on success, zero on failure.
}
/*
- * Reallocate cache for table EP to hold COUNT slots.
+ * Reallocate cache for table @ep to hold @count slots.
* The table must not be allocated statically.
* The cache may still be unmapped.
* If reallocation succeeds, any pointers obtained from ef_ptr()
}
/*
- * Open the table TYPE, which is a view of a base table
+ * Open the table @type, which is a view of a base table
* The table must not be already open.
* Return non-zero on success, zero on failure.
* Beware: views work only as long as the base table doesn't change size!
}
/*
- * Close the open table TYPE (EF_SECTOR, ...).
+ * Close the open table @type (EF_SECTOR, ...).
* Return non-zero on success, zero on failure.
*/
int
}
/*
- * Flush file-backed table TYPE (EF_SECTOR, ...) to its backing file.
+ * Flush file-backed table @type (EF_SECTOR, ...) to its backing file.
* Do nothing if the table is privately mapped.
* Update timestamps of written elements if table is EFF_TYPED.
* Return non-zero on success, zero on failure.
}
/*
- * Return pointer to element ID in table TYPE if it exists, else NULL.
+ * Return pointer to element @id in table @type if it exists, else NULL.
* The table must be fully cached, i.e. flags & EFF_MEM.
* The caller is responsible for flushing changes he makes.
*/
}
/*
- * Read element ID from table TYPE into buffer INTO.
+ * Read element @id from table @type into buffer @into.
* FIXME pass buffer size!
- * INTO is marked fresh with ef_mark_fresh().
+ * @into is marked fresh with ef_mark_fresh().
* Return non-zero on success, zero on failure.
*/
int
}
/*
- * Fill cache of file-backed EP with elements starting at ID.
+ * Fill cache of file-backed @ep with elements starting at @id.
* If any were read, return their number.
* Else return -1 and leave the cache unchanged.
*/
}
/*
- * Write COUNT elements starting at ID from BUF to file-backed EP.
+ * Write @count elements starting at @id from @buf to file-backed @ep.
* Update the timestamp if the table is EFF_TYPED.
* Don't actually write if table is privately mapped.
* Return 0 on success, -1 on error (file may be corrupt then).
}
/*
- * Write element ID into table TYPE from buffer FROM.
+ * Write element @id into table @type from buffer @from.
* FIXME pass buffer size!
- * Update timestamp in FROM if table is EFF_TYPED.
+ * Update timestamp in @from if table is EFF_TYPED.
* If table is file-backed and not privately mapped, write through
* cache straight to disk.
* Cannot write beyond the end of fully cached table (flags & EFF_MEM).
* Can write at the end of partially cached table.
- * FROM must be fresh; see ef_make_stale().
+ * @from must be fresh; see ef_make_stale().
* Return non-zero on success, zero on failure.
*/
int
/*
* Change element id.
- * BUF is an element of table TYPE.
- * ID is its new element ID.
- * If table is EFF_TYPED, change id and sequence number stored in BUF.
+ * @buf is an element of table @type.
+ * @id is its new element ID.
+ * If table is EFF_TYPED, change id and sequence number stored in @buf.
* Else do nothing.
*/
void
}
/*
- * Return sequence number of element ID in table EP.
+ * Return sequence number of element @id in table @ep.
* Return zero if table is not EFF_TYPED (it has no sequence number
* then).
*/
}
/*
- * Increment sequence number in BUF, which is about to be written to EP.
+ * Increment sequence number in @buf, which is about to be written to @ep.
* Do nothing if table is not EFF_TYPED (it has no sequence number
* then).
- * Else, BUF's sequence number must match the one in EP's cache. If
+ * Else, @buf's sequence number must match the one in @ep's cache. If
* it doesn't, we're about to clobber a previous write.
*/
static void
}
/*
- * Extend table TYPE by COUNT elements.
+ * Extend table @type by @count elements.
* Any pointers obtained from ef_ptr() become invalid.
* Return non-zero on success, zero on failure.
*/
}
/*
- * Initialize element ID for table TYPE in BUF.
+ * Initialize element @id for table @type in @buf.
* FIXME pass buffer size!
- * BUF is marked fresh with ef_mark_fresh().
+ * @buf is marked fresh with ef_mark_fresh().
*/
void
ef_blank(int type, int id, void *buf)
}
/*
- * Initialize COUNT elements of EP in BUF, starting with element ID.
+ * Initialize @count elements of @ep in @buf, starting with element @id.
*/
static void
do_blank(struct empfile *ep, void *buf, int id, int count)
}
/*
- * Truncate table TYPE to COUNT elements.
+ * Truncate table @type to @count elements.
* Any pointers obtained from ef_ptr() become invalid.
* Return non-zero on success, zero on failure.
*/
}
/*
- * Search for a table matching NAME, return its table type.
+ * Search for a table matching @name, return its table type.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several.
*/
}
/*
- * Search CHOICES[] for a table type matching NAME, return it.
+ * Search @choices[] for a table type matching @name, return it.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several.
- * CHOICES[] must be terminated with a negative value.
+ * @choices[] must be terminated with a negative value.
*/
int
ef_byname_from(char *name, int choices[])
}
/*
- * Return name of table TYPE. Always a single, short word.
+ * Return name of table @type. Always a single, short word.
*/
char *
ef_nameof(int type)
}
/*
- * Return "pretty" name of table TYPE.
+ * Return "pretty" name of table @type.
*/
char *
ef_nameof_pretty(int type)
}
/*
- * Ensure table contains element ID.
- * If necessary, extend it in steps of COUNT elements.
+ * Ensure table contains element @id.
+ * If necessary, extend it in steps of @count elements.
* Return non-zero on success, zero on failure.
*/
int
}
/*
- * Return maximum ID acceptable for table TYPE.
+ * Return maximum ID acceptable for table @type.
* Assuming infinite memory and disk space.
*/
int
}
/*
- * Record an update in the game file, the current time is NOW.
+ * Record an update in the game file, the current time is @now.
* This starts the Empire clock if it hasn't been started yet.
*/
void
}
/*
- * Set ETU timestamp *TICK to the current ETU time.
+ * Set ETU timestamp *@tick to the current ETU time.
* Return by how many ETUs it was increased.
*/
int
}
/*
- * Set ETU timestamp *TICK to the ETU time recorded in the game struct.
+ * Set ETU timestamp *@tick to the ETU time recorded in the game struct.
* The Empire clock is not updated.
* Return by how many ETUs it was increased.
*/
}
/*
- * Reset ETU timestamp *TICK to zero.
+ * Reset ETU timestamp *@tick to zero.
* Return how many ETUs it had left until etu_per_update.
*/
int
static char *daytime_range(char *str, int *from_min, int *to_min);
/*
- * Is week day WDAY (Sunday is 0) allowed by restriction DAYS?
- * If DAYS is not empty, it lists the allowed week day names. See
+ * Is week day @wday (Sunday is 0) allowed by restriction @days?
+ * If @days is not empty, it lists the allowed week day names. See
* weekday() for syntax.
*/
int
}
/*
- * Is day time DTIME (minutes since midnight) allowed by restriction TIMES?
- * If TIMES is not empty, it lists the allowed day time ranges. See
+ * Is day time @dtime (minutes since midnight) allowed by restriction @times?
+ * If @times is not empty, it lists the allowed day time ranges. See
* daytime_range() for syntax.
*/
int
}
/*
- * Parse weekday name in STR.
- * On success assign day number (Sunday is 0) to *WDAY and return
+ * Parse weekday name in @str.
+ * On success assign day number (Sunday is 0) to *@wday and return
* pointer to first character not parsed.
* Else return NULL.
* Abbreviated names are recognized, but not single characters.
}
/*
- * Parse day time in STR.
- * On success store minutes since midnight in *MIN and return pointer
+ * Parse day time in @str.
+ * On success store minutes since midnight in *@min and return pointer
* to first character not parsed.
* Else return NULL.
* Time format is HOUR:MINUTE. Initial whitespace is ignored.
}
/*
- * Parse a day time range in STR.
- * On success store minutes since midnight in *FROM and *TO, return
+ * Parse a day time range in @str.
+ * On success store minutes since midnight in *@from and *@to, return
* pointer to first character not parsed.
* Else return NULL.
* Format is HOUR:MINUTE-HOUR:MINUTE. Initial whitespace is ignored.
}
/*
- * Create an empty telegram file named MBOX.
+ * Create an empty telegram file named @mbox.
* Return 0 on success, -1 on failure.
*/
int
}
/*
- * Read telegram header from FP into TEL.
- * MBOX is the file name, it is used for logging errors.
+ * Read telegram header from @fp into @tel.
+ * @mbox is the file name, it is used for logging errors.
* Return 1 on success, 0 on EOF, -1 on error.
*/
int
}
/*
- * Read telegram body from FP.
- * MBOX is the file name, it is used for logging errors.
- * TEL is the header.
- * Unless SINK is null, it is called like SINK(CHUNK, SZ, ARG) to
+ * Read telegram body from @fp.
+ * @mbox is the file name, it is used for logging errors.
+ * @tel is the header.
+ * Unless @sink is null, it is called like @sink(CHUNK, SZ, @arg) to
* consume the body, chunk by chunk. The chunks are UTF-8, and
- * CHUNK[SZ} is 0. Reading fails when SINK() returns a negative
+ * CHUNK[SZ} is 0. Reading fails when @sink() returns a negative
* value.
* Return 0 on success, -1 on failure.
*/
}
/*
- * Return relations US has with THEM.
+ * Return relations @us has with @them.
* Countries are considered allied to themselves.
*/
int
}
/*
- * Initialize NATP for country #CNUM in status STAT.
- * STAT must be STAT_UNUSED, STAT_NEW, STAT_VIS or STAT_GOD.
+ * Initialize @natp for country #@cnum in status @stat.
+ * @stat must be STAT_UNUSED, STAT_NEW, STAT_VIS or STAT_GOD.
* Also wipe realms and telegrams.
*/
struct natstr *
#include "optlist.h"
/*
- * Initialize VAL to symbolic value for selector CA with index IDX.
- * Return VAL.
+ * Initialize @val to symbolic value for selector @ca with index @idx.
+ * Return @val.
*/
struct valstr *
nstr_mksymval(struct valstr *val, struct castr *ca, int idx)
}
/*
- * Evaluate VAL.
- * If VAL has category NSC_OFF, read the value from the context object
- * PTR, and translate it for country CNUM (coordinate system and
- * contact status). No translation when CNUM is NATID_BAD.
- * PTR points to a context object of the type that was used to compile
+ * Evaluate @val.
+ * If @val has category NSC_OFF, read the value from the context object
+ * @ptr, and translate it for country @cnum (coordinate system and
+ * contact status). No translation when @cnum is NATID_BAD.
+ * @ptr points to a context object of the type that was used to compile
* the value.
- * Unless WANT is NSC_NOTYPE, coerce the value to promoted value type
- * WANT. VAL must be coercible.
+ * Unless @want is NSC_NOTYPE, coerce the value to promoted value type
+ * @want. @val must be coercible.
* The result's type is promoted on success, NSC_NOTYPE on error.
* In either case, the category is NSC_VAL.
- * Return VAL.
+ * Return @val.
*/
struct valstr *
nstr_eval(struct valstr *val, natid cnum, void *ptr, enum nsc_type want)
}
/*
- * Promote VALTYPE.
- * If VALTYPE is an integer type, return NSC_LONG.
- * If VALTYPE is a floating-point type, return NSC_DOUBLE.
- * If VALTYPE is a string type, return NSC_STRING.
+ * Promote @valtype.
+ * If @valtype is an integer type, return NSC_LONG.
+ * If @valtype is a floating-point type, return NSC_DOUBLE.
+ * If @valtype is a string type, return NSC_STRING.
*/
int
nstr_promote(int valtype)
#endif /* !PATH_FIND_STATS */
#ifndef NDEBUG /* silence "not used" warning */
-/* Is sector with uid UID open? */
+/* Is sector with uid @uid open? */
static int
pf_is_open(int uid)
{
}
#endif
-/* Is sector with uid UID closed? */
+/* Is sector with uid @uid closed? */
static int
pf_is_closed(int uid)
{
return pf_map[uid].visit > pf_visit;
}
-/* Is sector with uid UID unvisited? */
+/* Is sector with uid @uid unvisited? */
static int
pf_is_unvisited(int uid)
{
#define pf_check() ((void)0)
#endif
-/* Swap pf_heap's I-th and J-th elements. */
+/* Swap pf_heap's @i-th and @j-th elements. */
static void
pf_heap_swap(int i, int j)
{
pf_map[pf_heap[j].uid].heapi = j;
}
-/* Restore heap property after N-th element's cost increased. */
+/* Restore heap property after @n-th element's cost increased. */
static void
pf_sift_down(int n)
{
}
}
-/* Restore heap property after N-th element's cost decreased. */
+/* Restore heap property after @n-th element's cost decreased. */
static void
pf_sift_up(int n)
{
}
/*
- * Open the unvisited sector X,Y.
- * UID is sector uid, it equals XYOFFSET(X,Y).
- * Cheapest path from source comes from direction DIR and has cost COST.
+ * Open the unvisited sector @x,@y.
+ * @uid is sector uid, it equals XYOFFSET(@x,@y).
+ * Cheapest path from source comes from direction @dir and has cost @cost.
*/
static void
pf_open(int uid, coord x, coord y, int dir, double cost)
/* silence "not used" warning */
#ifdef PATH_FIND_DEBUG
/*
- * Return cost from source to sector with uid UID.
+ * Return cost from source to sector with uid @uid.
* It must be visited, i.e. open or closed.
*/
static double
/*
* Set the current source and cost function.
- * SX,SY is the source.
- * The cost to enter the sector with uid u is COST(ACTOR, u).
+ * @sx,@sy is the source.
+ * The cost to enter the sector with uid u is @cost(@actor, u).
* Negative value means the sector can't be entered.
*/
static void
}
/*
- * Find cheapest path from current source to DX,DY, return its cost.
+ * Find cheapest path from current source to @dx,@dy, return its cost.
*/
double
path_find_to(coord dx, coord dy)
}
/*
- * Write route from SX,SY to DX,DY to BUF[BUFSIZ], return its length.
- * If the route is longer than BUFSIZ-1 characters, it's truncated.
+ * Write route from @sx,@sy to @dx,@dy to @buf[@bufsiz], return its length.
+ * If the route is longer than @bufsiz-1 characters, it's truncated.
* You must compute path cost first, with path_find_to().
- * SX,SY must be on a shortest path from the current source to DX,DY.
+ * @sx,@sy must be on a shortest path from the current source to @dx,@dy.
*/
size_t
path_find_route(char *buf, size_t bufsz,
}
/*
- * Rotate BUF[BUFSZ] to put BUF[I] into BUF[0], and zero-terminate.
+ * Rotate @buf[@bufsz] to put @buf[@i] into @buf[0], and zero-terminate.
*/
static char *
bufrotate(char *buf, size_t bufsz, size_t i)
};
/*
- * Start finding paths from SX,SY.
- * Use mobility costs for ACTOR and MOBTYPE.
+ * Start finding paths from @sx,@sy.
+ * Use mobility costs for @actor and @mobtype.
*/
void
path_find_from(coord sx, coord sy, natid actor, int mobtype)
}
/*
- * Find cheapest path from SX,SY to DX,DY, return its mobility cost.
- * Use mobility costs for ACTOR and MOBTYPE.
+ * Find cheapest path from @sx,@sy to @dx,@dy, return its mobility cost.
+ * Use mobility costs for @actor and @mobtype.
*/
double
path_find(coord sx, coord sy, coord dx, coord dy, natid actor, int mobtype)
static int delete_update(time_t, time_t[], int);
/*
- * Read update schedule from file FNAME.
- * Put the first N-1 updates after T0 into SCHED[] in ascending order,
+ * Read update schedule from file @fname.
+ * Put the first @n-1 updates after @t0 into @sched[] in ascending order,
* terminated with a zero.
- * Use ANCHOR as initial anchor for anchor-relative times.
+ * Use @anchor as initial anchor for anchor-relative times.
* Return 0 on success, -1 on failure.
*/
int
}
/*
- * Parse an update schedule directive from LINE.
- * Update SCHED[] and ANCHOR accordingly.
- * SCHED[] holds the first N-1 updates after T0 in ascending order.
- * FNAME and LNO file name and line number for reporting errors.
+ * Parse an update schedule directive from @line.
+ * Update @sched[] and @anchor accordingly.
+ * @sched[] holds the first N-1 updates after @t0 in ascending order.
+ * @fname and @lno file name and line number for reporting errors.
*/
static int
parse_schedule_line(char *line, time_t sched[], int n,
}
/*
- * Complain and return zero when T is bad, else return non-zero.
- * FNAME and LNO file name and line number.
+ * Complain and return zero when @t is bad, else return non-zero.
+ * @fname and @lno file name and line number.
*/
static int
time_ok(time_t t, char *fname, int lno)
}
/*
- * Parse a time from S into *T.
- * *ANCHOR is the base for anchor-relative time.
+ * Parse a time from @s into *@t.
+ * *@anchor is the base for anchor-relative time.
* Return pointer to first character not parsed on success,
* null pointer on failure.
*/
}
/*
- * Parse an every clause from S into *SECS.
+ * Parse an every clause from @s into *@secs.
* Return pointer to first character not parsed on success,
* null pointer on failure.
*/
}
/*
- * Parse an until clause from S into *T.
- * *ANCHOR is the base for anchor-relative time.
+ * Parse an until clause from @s into *@t.
+ * *@anchor is the base for anchor-relative time.
* Return pointer to first character not parsed on success,
* null pointer on failure.
*/
}
/*
- * Parse an skip clause from S into *T.
- * *ANCHOR is the base for anchor-relative time.
+ * Parse an skip clause from @s into *@t.
+ * *@anchor is the base for anchor-relative time.
* Return pointer to first character not parsed on success,
* null pointer on failure.
*/
}
/*
- * Return the index of the first update at or after T in SCHED[].
+ * Return the index of the first update at or after @t in @sched[].
*/
static int
find_update(time_t t, time_t sched[])
}
/*
- * Insert update at T into SCHED[].
- * SCHED[] holds the first N-1 updates after T0 in ascending order.
- * If T is before T0 or outside game_days/game_hours, return -1.
- * If there's no space for T in SCHED[], return N-1.
- * Else insert T into SCHED[] and return its index in SCHED[].
+ * Insert update at @t into @sched[].
+ * @sched[] holds the first @n-1 updates after @t0 in ascending order.
+ * If @t is before @t0 or outside game_days/game_hours, return -1.
+ * If there's no space for @t in @sched[], return N-1.
+ * Else insert @t into @sched[] and return its index in @sched[].
*/
static int
insert_update(time_t t, time_t sched[], int n, time_t t0)
}
/*
- * Delete update T from SCHED[].
- * SCHED[] holds N-1 updates in ascending order.
- * Return the index of the first update after T in SCHED[].
+ * Delete update @t from @sched[].
+ * @sched[] holds @n-1 updates in ascending order.
+ * Return the index of the first update after @t in @sched[].
*/
static int
delete_update(time_t t, time_t sched[], int n)
#include "match.h"
/*
- * Find element named NEEDLE in array HAYSTACK[], return its index.
+ * Find element named @needle in array @haystack[], return its index.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several.
- * Each array element has a pointer to its name stored at offset OFFS.
+ * Each array element has a pointer to its name stored at offset @offs.
* Search stops when this name is a null pointer.
* It ignores elements with an empty name.
- * NEEDLE is compared to element names with mineq(NEEDLE, NAME).
- * SIZE gives the size of an array element.
+ * @needle is compared to element names with mineq(@needle, NAME).
+ * @size gives the size of an array element.
*/
int
stmtch(char *needle, void *haystack, ptrdiff_t offs, size_t size)
}
/*
- * Compare A with B.
- * Return ME_EXACT if they are the same, or A is a prefix of B
- * followed by a space in B.
- * Return ME_PARTIAL if A is a prefix of B not followed by a space.
+ * Compare @a with @b.
+ * Return ME_EXACT if they are the same, or @a is a prefix of @b
+ * followed by a space in @b.
+ * Return ME_PARTIAL if @a is a prefix of @b not followed by a space.
* Else return ME_MISMATCH.
*/
int
#include "ship.h"
/*
- * Return index of sector called NAME in dchr[], or M_NOTFOUND.
+ * Return index of sector called @name in dchr[], or M_NOTFOUND.
*/
int
sct_typematch(char *name)
}
/*
- * Search table TYPE for an element matching NAME, return its index.
+ * Search table @type for an element matching @name, return its index.
* Accepts EF_BAD, but of course never finds anything then.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several.
#include "xdump.h"
/*
- * Initialize XD.
- * Translate dump for country CNUM, except when CNUM is NATID_BAD.
- * If HUMAN, dump in human-readable format.
- * If SLOPPY, try to cope with invalid data (may result in invalid
+ * Initialize @xd.
+ * Translate dump for country @cnum, except when @cnum is NATID_BAD.
+ * If @human, dump in human-readable format.
+ * If @sloppy, try to cope with invalid data (may result in invalid
* dump).
- * Dump is to be delivered through callback PR.
- * Return XD.
+ * Dump is to be delivered through callback @pr.
+ * Return @xd.
*/
struct xdstr *
xdinit(struct xdstr *xd, natid cnum, int human, int sloppy,
}
/*
- * Evaluate a attribute of an object into VAL, return VAL.
- * CA describes the attribute.
- * XD is the xdump descriptor.
- * PTR points to the context object.
- * IDX is the index within the attribute.
+ * Evaluate a attribute of an object into @val, return @val.
+ * @ca describes the attribute.
+ * @xd is the xdump descriptor.
+ * @ptr points to the context object.
+ * @idx is the index within the attribute.
*/
static struct valstr *
xdeval(struct valstr *val, struct xdstr *xd,
}
/*
- * Dump string STR to XD with funny characters escaped.
- * Dump at most N characters.
+ * Dump string @str to @xd with funny characters escaped.
+ * Dump at most @n characters.
*/
static void
xdpresc(struct xdstr *xd, char *str, size_t n)
}
/*
- * Dump VAL prefixed with SEP to XD, in machine readable format.
- * VAL must be evaluated.
+ * Dump @val prefixed with @sep to @xd, in machine readable format.
+ * @val must be evaluated.
* Return " ".
*/
static char *
}
/*
- * Dump symbol with value KEY from symbol table TYPE to XD.
- * Prefix with SEP, return " ".
+ * Dump symbol with value @key from symbol table @type to @xd.
+ * Prefix with @sep, return " ".
*/
static char *
xdprsym(struct xdstr *xd, int key, int type, char *sep)
}
/*
- * Dump VAL prefixed with SEP to XD, return " ".
- * VAL must be evaluated.
- * CA describes the field from which the value was fetched.
+ * Dump @val prefixed with @sep to @xd, return " ".
+ * @val must be evaluated.
+ * @ca describes the field from which the value was fetched.
*/
static char *
xdprval_sym(struct xdstr *xd, struct valstr *val, struct castr *ca,
}
/*
- * Dump field values of a context object to XD.
- * CA[] describes fields.
- * PTR points to context object.
+ * Dump field values of a context object to @xd.
+ * @ca[] describes fields.
+ * @ptr points to context object.
*/
void
xdflds(struct xdstr *xd, struct castr ca[], void *ptr)
}
/*
- * Dump header for dump NAME to XD.
- * If META, it's for the meta-data dump rather than the data dump.
+ * Dump header for dump @name to @xd.
+ * If @meta, it's for the meta-data dump rather than the data dump.
*/
void
xdhdr(struct xdstr *xd, char *name, int meta)
}
/*
- * Dump column header to XD.
- * CA[] describes fields.
- * Does nothing unless XD is human-readable.
+ * Dump column header to @xd.
+ * @ca[] describes fields.
+ * Does nothing unless @xd is human-readable.
*/
void
xdcolhdr(struct xdstr *xd, struct castr ca[])
static int xutail(FILE *, struct castr *);
/*
- * Does the code hardcode indexes for table TYPE?
+ * Does the code hardcode indexes for table @type?
*/
static int
have_hardcoded_indexes(int type)
}
/*
- * Okay to truncate table TYPE?
+ * Okay to truncate table @type?
*/
static int
may_truncate(int type)
}
/*
- * Is TYPE's 0-th selector a usable ID?
+ * Is @type's 0-th selector a usable ID?
*/
static int
ca0_is_id(int type)
}
/*
- * Can we fill in gaps in table TYPE?
+ * Can we fill in gaps in table @type?
*/
static int
can_fill_gaps(int type)
}
/*
- * Is table TYPE's ID-th record OBJ redundant for xundump()
+ * Is table @type's @id-th record @obj redundant for xundump()
*/
int
xundump_redundant(int type, int id, void *obj)
}
/*
- * Seek to current table's ID-th object.
+ * Seek to current table's @id-th object.
* Extend the table if necessary.
- * Save ID in cur_id.
+ * Save @id in cur_id.
* Return the object on success, NULL on failure.
*/
static void *
}
/*
- * Omit ID1..ID2-1.
+ * Omit @id1..@id2-1.
* Reset the omitted objects to default state.
*/
static void
}
/*
- * Return the smallest non-omitted ID in ID1..ID2-1 if any, else -1.
+ * Return the smallest non-omitted ID in @id1..@id2-1 if any, else -1.
*/
static int
expected_id(int id1, int id2)
}
/*
- * Get selector for field FLDNO.
- * Assign the field's selector index to *IDX, unless it is null.
+ * Get selector for field @fldno.
+ * Assign the field's selector index to *@idx, unless it is null.
* Return the selector on success, null pointer on error.
*/
static struct castr *
}
/*
- * Find the field for selector CA with index IDX.
+ * Find the field for selector @ca with index @idx.
* Return the field number if it exists, else -1.
*/
static int
}
/*
- * Find the field NAME with index IDX and value representable as long.
+ * Find the field @name with index @idx and value representable as long.
* Return the field number if it exists, else -1.
*/
static int
}
/*
- * Is a new value for field FLDNO required to match the old one?
+ * Is a new value for field @fldno required to match the old one?
*/
static int
fldval_must_match(int fldno)
}
/*
- * Set OBJ's field FLDNO to DBL.
+ * Set @obj's field @fldno to @dbl.
* Return 0 on success, -1 on error.
*/
static int
}
/*
- * Set obj's field FLDNO to STR.
+ * Set obj's field @fldno to @str.
* Return 0 on success, -1 on error.
*/
static int
}
/*
- * Read and ignore field separators from FP.
+ * Read and ignore field separators from @fp.
* Return first character that is not a field separator.
*/
static int
}
/*
- * Decode escape sequences in BUF.
- * Return BUF on success, null pointer on failure.
+ * Decode escape sequences in @buf.
+ * Return @buf on success, null pointer on failure.
*/
static char *
xuesc(char *buf)
}
/*
- * Read an identifier from FP into BUF.
- * BUF must have space for 1024 characters.
+ * Read an identifier from @fp into @buf.
+ * @buf must have space for 1024 characters.
* Return number of characters read on success, -1 on failure.
*/
static int
}
/*
- * Try to read a field name from FP.
- * I is the field number, counting from zero.
- * If a name is read, set fldca[I] and fldidx[I] for it, and update
+ * Try to read a field name from @fp.
+ * @i is the field number, counting from zero.
+ * If a name is read, set fldca[@i] and fldidx[@i] for it, and update
* caflds[].
* Return 1 if a name or ... was read, 0 on end of line, -1 on error.
*/
}
/*
- * Try to read a field value from FP.
- * I is the field number, counting from zero.
+ * Try to read a field value from @fp.
+ * @i is the field number, counting from zero.
* Return 1 if a value was read, 0 on end of line, -1 on error.
*/
static int
}
/*
- * Read fields from FP.
- * Use PARSE() to read each field.
+ * Read fields from @fp.
+ * Use @parse() to read each field.
* Return number of fields read on success, -1 on error.
*/
static int
}
/*
- * Define the FLDNO-th field.
- * If IDX is negative, define as selector NAME, else as NAME(IDX).
- * Set fldca[FLDNO] and fldidx[FLDNO] accordingly.
+ * Define the @fldno-th field.
+ * If @idx is negative, define as selector @name, else as @name(@idx).
+ * Set fldca[@fldno] and fldidx[@fldno] accordingly.
* Update caflds[].
* Return 1 on success, -1 on error.
*/
}
/*
- * Set value of field FLDNO in current row to DBL.
+ * Set value of field @fldno in current row to @dbl.
* Return 1 on success, -1 on error.
*/
static int
}
/*
- * Set value of field FLDNO in current row to STR.
+ * Set value of field @fldno in current row to @str.
* Return 1 on success, -1 on error.
*/
static int
}
/*
- * Resolve symbol name ID in table referred to by CA.
- * Use field number N for error messages.
+ * Resolve symbol name @id in table referred to by @ca.
+ * Use field number @n for error messages.
* Return index in referred table on success, -1 on failure.
*/
static int
/*
* Map symbol index to symbol value.
- * CA is the table, and I is the index in it.
+ * @ca is the table, and @i is the index in it.
*/
static int
symval(struct castr *ca, int i)
}
/*
- * Set value of field FLDNO in current object to value of symbol SYM.
+ * Set value of field @fldno in current object to value of symbol @sym.
* Return 1 on success, -1 on error.
*/
static int
}
/*
- * Create an empty symbol set for field FLDNO in *SET.
+ * Create an empty symbol set for field @fldno in *@set.
* Return 1 on success, -1 on error.
*/
static int
}
/*
- * Add a symbol to a symbol set for field FLDNO in *SET.
- * SYM is the name of the symbol to add.
+ * Add a symbol to a symbol set for field @fldno in *@set.
+ * @sym is the name of the symbol to add.
* Return 1 on success, -1 on error.
*/
static int
}
/*
- * Read an xdump table header line from FP.
- * Expect header for EXPECTED_TABLE, unless it is EF_BAD.
+ * Read an xdump table header line from @fp.
+ * Expect header for @expected_table, unless it is EF_BAD.
* Recognize header for machine- and human-readable syntax, and set
* human accordingly.
* Return table type on success, -2 on EOF before header, -1 on failure.
/*
* Find fields in this xdump.
- * If reading human-readable syntax, read a field header line from FP.
- * Else take fields from the table's selectors in CA[].
+ * If reading human-readable syntax, read a field header line from @fp.
+ * Else take fields from the table's selectors in @ca[].
* Set ellipsis, nflds, fldca[], fldidx[] and caflds[] accordingly.
* Return 0 on success, -1 on failure.
*/
}
/*
- * Read xdump footer from FP.
- * CA[] contains the table's selectors.
- * The body had RECS records.
+ * Read xdump footer from @fp.
+ * @ca[] contains the table's selectors.
+ * The body had @recs records.
* Update cafldspp[] from caflds[].
* Return 0 on success, -1 on failure.
*/
}
/*
- * Read an xdump table from FP.
+ * Read an xdump table from @fp.
* Both machine- and human-readable xdump syntax are recognized.
- * Expect table EXPECTED_TABLE, unless it is EF_BAD.
+ * Expect table @expected_table, unless it is EF_BAD.
* Report errors to stderr.
- * Messages assume FP starts in the file FILE at line *PLNO.
- * Update *PLNO to reflect lines read from FP.
+ * Messages assume @fp starts in the file @file at line *@plno.
+ * Update *@plno to reflect lines read from @fp.
* Return table type on success, -2 on EOF before header, -1 on failure.
*/
int
}
/*
- * Read the remainder of an xdump after the table header line from FP.
- * CA[] contains the table's selectors.
+ * Read the remainder of an xdump after the table header line from @fp.
+ * @ca[] contains the table's selectors.
* Return 0 on success, -1 on failure.
*/
static int
}
/*
- * Read the body of an xdump table from FP.
+ * Read the body of an xdump table from @fp.
* Return number of rows read on success, -1 on failure.
*/
static int
}
/*
- * Convert initial part of STR to normalized x-coordinate.
+ * Convert initial part of @str to normalized x-coordinate.
* Return -1 on error. This works, as normalized coordinates are
* non-negative.
- * Assign pointer to first character after the coordinate to *END,
- * unless END is a null pointer.
+ * Assign pointer to first character after the coordinate to *@end,
+ * unless @end is a null pointer.
*/
coord
strtox(char *str, char **end)
}
/*
- * Convert initial part of STR to normalized y-coordinate.
+ * Convert initial part of @str to normalized y-coordinate.
* Return -1 on error. This works, as normalized coordinates are
* non-negative.
- * Assign pointer to first character after the coordinate to *END,
- * unless END is a null pointer.
+ * Assign pointer to first character after the coordinate to *@end,
+ * unless @end is a null pointer.
*/
coord
strtoy(char *str, char **end)
}
/*
- * Close IOP.
+ * Close @iop.
* Flush output and wait for the client to close the connection.
- * Wait at most until DEADLINE. (time_t)-1 means wait as long as it
+ * Wait at most until @deadline. (time_t)-1 means wait as long as it
* takes (no timeout).
* Both the flush and the wait can be separately cut short by
* empth_wakeup(). This is almost certainly not what you want. If
}
/*
- * Read input from IOP and enqueue it.
- * Wait at most until DEADLINE for input to arrive. (time_t)-1 means
+ * Read input from @iop and enqueue it.
+ * Wait at most until @deadline for input to arrive. (time_t)-1 means
* wait as long as it takes (no timeout).
- * Does not yield the processor when DEADLINE is zero.
+ * Does not yield the processor when @deadline is zero.
* A wait for input can be cut short by empth_wakeup().
* Return number of bytes read on success, -1 on error.
* In particular, return zero on timeout, early wakeup or EOF. Use
}
/*
- * Write output queued in IOP.
- * Wait at most until DEADLINE for input to arrive. (time_t)-1 means
+ * Write output queued in @iop.
+ * Wait at most until @deadline for input to arrive. (time_t)-1 means
* wait as long as it takes (no timeout).
- * Does not yield the processor when DEADLINE is zero.
+ * Does not yield the processor when @deadline is zero.
* A wait for output can be cut short by empth_wakeup().
* Return number of bytes written on success, -1 on error.
* In particular, return zero when nothing was written because the
}
/*
- * Write output queued in IOP if enough have been enqueued.
+ * Write output queued in @iop if enough have been enqueued.
* Write if at least one buffer has been filled since the last write.
- * Wait at most until DEADLINE for output to be accepted. (time_t)-1
+ * Wait at most until @deadline for output to be accepted. (time_t)-1
* means wait as long as it takes (no timeout).
- * Does not yield the processor when DEADLINE is zero.
+ * Does not yield the processor when @deadline is zero.
* A wait for output can be cut short by empth_wakeup().
* Return number of bytes written on success, -1 on error.
* In particular, return zero when nothing was written because the
}
/*
- * Discard IOP's buffered input and set its EOF flag.
- * No more input can be read from IOP.
+ * Discard @iop's buffered input and set its EOF flag.
+ * No more input can be read from @iop.
*/
void
io_set_eof(struct iop *iop)
}
/*
- * Return non-zero with probability PCT%.
+ * Return non-zero with probability @pct%.
*/
int
pct_chance(int pct)
}
/*
- * Round VAL to nearest integer (on the average).
- * VAL's fractional part is chance to round up.
+ * Round @val to nearest integer (on the average).
+ * @val's fractional part is chance to round up.
*/
int
roundavg(double val)
}
/*
- * Seed the pseudo-random number generator with SEED.
+ * Seed the pseudo-random number generator with @seed.
* The sequence of pseudo-random numbers is repeatable by seeding it
* with the same value.
*/
static int fname_is_abs(const char *);
/*
- * Interpret FNAME relative to directory DIR.
- * Return FNAME if it is absolute, or DIR is null or empty.
- * Else return a malloc'ed string containing DIR/FNAME, or null
+ * Interpret @fname relative to directory @dir.
+ * Return @fname if it is absolute, or @dir is null or empty.
+ * Else return a malloc'ed string containing @dir/@fname, or null
* pointer when that fails.
*/
char *
/*
* Open a stream like fopen(), optionally relative to a directory.
- * This is exactly like fopen(), except FNAME is interpreted relative
- * to DIR if that is neither null nor empty.
+ * This is exactly like fopen(), except @fname is interpreted relative
+ * to @dir if that is neither null nor empty.
*/
FILE *
fopenat(const char *fname, const char *mode, const char *dir)
}
/*
- * Return the preferred block size for I/O on FD.
+ * Return the preferred block size for I/O on @fd.
*/
int
blksize(int fd)
static int logopen(void);
/*
- * Points log file at PROGRAM.log
+ * Points log file at @program.log
*/
int
loginit(char *program)
}
/*
- * Log internal error MSG occured in FILE:LINE, call oops handler.
+ * Log internal error @msg occured in @file:@line, call oops handler.
*/
void
oops(char *msg, char *file, int line)
#include "prototypes.h"
/*
- * Parse user command in BUF.
- * BUF is UTF-8.
- * Command name and arguments are copied into SPACE[], whose size must
- * be at least strlen(BUF) + 1.
- * Set ARG[0] to the zero-terminated command name.
- * Set ARG[1..N] to the zero-terminated arguments, where N is the
- * number of arguments. Set ARG[N+1..127] to NULL.
- * Set TAIL[0..N] to beginning of ARG[0] in BUF[].
- * If CONDP is not null, recognize conditional argument syntax, and
- * set *CONDP to the conditional argument if present, else NULL.
- * If REDIR is not null, recognize redirection syntax, and set *REDIR
+ * Parse user command in @buf.
+ * @buf is UTF-8.
+ * Command name and arguments are copied into @space[], whose size must
+ * be at least strlen(@buf) + 1.
+ * Set @arg[0] to the zero-terminated command name.
+ * Set @arg[1..N] to the zero-terminated arguments, where N is the
+ * number of arguments. Set @arg[N+1..127] to NULL.
+ * Set @tail[0..N] to beginning of @arg[0] in @buf[].
+ * If @condp is not null, recognize conditional argument syntax, and
+ * set *@condp to the conditional argument if present, else NULL.
+ * If @redir is not null, recognize redirection syntax, and set *@redir
* to UTF-8 redirection string if present, else NULL.
- * Return number of slots used in ARG[], or -1 on error.
+ * Return number of slots used in @arg[], or -1 on error.
*/
int
parse(char *buf, char *space, char **arg,
}
/*
- * Wake up PROC if it is sleeping in lwpSleepFd().
+ * Wake up @proc if it is sleeping in lwpSleepFd().
* Must be followed by lwpWakeupSleep() before the next lwpReschedule().
*/
static void
static void lwpCatchAwaitedSig(int);
/*
- * Initialize waiting for signals in SET.
+ * Initialize waiting for signals in @set.
*/
void
lwpInitSigWait(sigset_t *set)
}
/*
- * Test whether a signal from SET has been catched.
+ * Test whether a signal from @set has been catched.
* If yes, delete that signal from the set of catched signals, and
* return its number.
* Else return 0.
}
/*
- * Wait until a signal from SET arrives.
- * Assign its number to *SIG and return 0.
+ * Wait until a signal from @set arrives.
+ * Assign its number to *@sig and return 0.
* If another thread is already waiting for signals, return EBUSY
* without waiting.
*/
}
/*
- * Return player in state PS_PLAYING for CNUM.
+ * Return player in state PS_PLAYING for @cnum.
*/
struct player *
getplayer(natid cnum)
/*
* Execute command named by player->argp[0].
- * BUF is the raw UTF-8 command line. It should have been passed to
+ * @buf is the raw UTF-8 command line. It should have been passed to
* parse() to set up player->argp.
- * If REDIR is not null, it's the command's redirection, in UTF-8.
+ * If @redir is not null, it's the command's redirection, in UTF-8.
* Return -1 if the command is not unique or doesn't exist, else 0.
*/
int
static void disable_coms(void);
/*
- * Get a command from the current player into COMBUFP[1024], in UTF-8.
+ * Get a command from the current player into @combufp[1024], in UTF-8.
* This may block for input, yielding the processor. Flush buffered
* output when blocking, to make sure player sees the prompt.
* Return command's byte length on success, -1 on error.
}
/*
- * Make all objects stale if ARG is one of the player's command arguments.
+ * Make all objects stale if @arg is one of the player's command arguments.
* See ef_make_stale() for what "making stale" means.
* Useful for functions that prompt for missing arguments.
* These can yield the processor, so we'd like to call ef_make_stale()
* Receive a line of input from the current player.
* If the player's aborted flag is set, return -1 without receiving
* input.
- * Else receive one line and store it in CMD[SIZE].
+ * Else receive one line and store it in @cmd[@size].
* This may block for input, yielding the processor. Flush buffered
* output when blocking, to make sure player sees the prompt.
* If the player's connection has the I/O error or EOF indicator set,
}
/*
- * Report deity meddling with sector SP.
+ * Report deity meddling with sector @sp.
* Print a message (always), send a bulletin to the sector owner and
* report news (sometimes).
- * NAME names what is being changed in the sector.
- * If CHANGE is zero, the meddling is a no-op (bulletin suppressed).
- * If CHANGE is negative, it's secret (bulletin suppressed).
- * If a bulletin is sent, report N_AIDS news for positive GOODNESS,
- * N_HURTS news for negative GOODNESS
- * The bulletin's text is like "NAME of sector X,Y changed <how> by an
+ * @name names what is being changed in the sector.
+ * If @change is zero, the meddling is a no-op (bulletin suppressed).
+ * If @change is negative, it's secret (bulletin suppressed).
+ * If a bulletin is sent, report N_AIDS news for positive @goodness,
+ * N_HURTS news for negative @goodness
+ * The bulletin's text is like "@name of sector X,Y changed <how> by an
* act of <deity>, where <deity> is the deity's name, and <how> comes
- * from formatting printf-style FMT with optional arguments.
+ * from formatting printf-style @fmt with optional arguments.
*/
void
divine_sct_change(struct sctstr *sp, char *name,
}
/*
- * Report deity meddling with NP.
+ * Report deity meddling with @np.
* Just like divine_sct_change(), only for nations.
*/
void
}
/*
- * Report deity meddling with UNIT.
+ * Report deity meddling with @unit.
* Just like divine_sct_change(), only for ships, planes, land units,
* nukes.
*/
}
/*
- * Report deity giving/taking commodities to/from WHOM.
- * Give AMT of IP in PLACE.
+ * Report deity giving/taking commodities to/from @whom.
+ * Give @amt of @ip in @place.
*/
void
report_divine_gift(natid whom, struct ichrstr *ip, int amt, char *place)
}
/*
- * Return path cost for ATTACKER to enter sector given by DEF.
- * MOBTYPE is a mobility type accepted by sector_mcost().
+ * Return path cost for @attacker to enter sector given by @def.
+ * @mobtype is a mobility type accepted by sector_mcost().
*/
static double
att_mobcost(natid attacker, struct combat *def, int mobtype)
static void knockdown(struct sctstr *);
/*
- * Is there support for a bridge at SP?
- * Ignore support coming from direction IGNORE_DIR.
+ * Is there support for a bridge at @sp?
+ * Ignore support coming from direction @ignore_dir.
*/
int
bridge_support_at(struct sctstr *sp, int ignore_dir)
}
/*
- * Check bridges at and around SP after damage to SP.
- * If SP is an inefficent bridge, splash it.
- * If SP can't support a bridge, splash unsupported adjacent bridges.
- * Write back splashed bridges, except for SP; writing that one is
+ * Check bridges at and around @sp after damage to @sp.
+ * If @sp is an inefficent bridge, splash it.
+ * If @sp can't support a bridge, splash unsupported adjacent bridges.
+ * Write back splashed bridges, except for @sp; writing that one is
* left to the caller.
*/
void
}
/*
- * Compute coastal flags for a change of SP from OLDDES to NEWDES.
- * Update adjacent sectors, but don't touch SP.
+ * Compute coastal flags for a change of @sp from @olddes to @newdes.
+ * Update adjacent sectors, but don't touch @sp.
*/
void
set_coastal(struct sctstr *sp, int olddes, int newdes)
}
/*
- * Ask user to confirm abandonment of sector SP, if any.
- * If removing AMNT commodities of type VTYPE and the land units in
- * LIST would abandon their sector, ask the user to confirm.
- * All land units in LIST must be in this sector. LIST may be null.
+ * Ask user to confirm abandonment of sector @sp, if any.
+ * If removing @amnt commodities of type @vtype and the land units in
+ * @list would abandon their sector, ask the user to confirm.
+ * All land units in @list must be in this sector. @list may be null.
* Return zero when abandonment was declined, else non-zero.
*/
int
}
/*
- * Would removing this stuff from SP abandon it?
- * Consider removal of AMNT commodities of type VTYPE and the land
- * units in LIST.
- * All land units in LIST must be in this sector. LIST may be null.
+ * Would removing this stuff from @sp abandon it?
+ * Consider removal of @amnt commodities of type @vtype and the land
+ * units in @list.
+ * All land units in @list must be in this sector. @list may be null.
*/
int
would_abandon(struct sctstr *sp, i_type vtype, int amnt,
}
/*
- * Shall CN attempt to help FRIEND against FOE?
+ * Shall @cn attempt to help @friend against @foe?
*/
int
feels_like_helping(natid cn, natid friend, natid foe)
static int tilde_escape(char *s);
/*
- * Read a telegram for RECIPIENT into BUF, in UTF-8.
- * BUF must have space for MAXTELSIZE+1 characters.
+ * Read a telegram for @recipient into @buf, in UTF-8.
+ * @buf must have space for MAXTELSIZE+1 characters.
* Return telegram length, or -1 on error.
*/
int
/*
* Get string argument.
- * If INPUT is not empty, use it, else prompt for more input using PROMPT.
- * Copy input to BUF[1024].
- * Return BUF on success, else NULL.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
+ * Copy input to @buf[1024].
+ * Return @buf on success, else NULL.
*/
char *
getstarg(char *input, char *prompt, char *buf)
#include "prototypes.h"
/*
- * Print sub-prompt PROMPT, receive a line of input into BUF[1024].
- * Return BUF on success, else NULL.
+ * Print sub-prompt @prompt, receive a line of input into @buf[1024].
+ * Return @buf on success, else NULL.
*/
char *
getstring(char *prompt, char *buf)
}
/*
- * Print sub-prompt PROMPT, receive a line of UTF-8 input into BUF[1024].
- * Return BUF on success, else NULL.
+ * Print sub-prompt @prompt, receive a line of UTF-8 input into @buf[1024].
+ * Return @buf on success, else NULL.
*/
char *
ugetstring(char *prompt, char *buf)
}
/*
- * Fire from fortress SP.
+ * Fire from fortress @sp.
* Use ammo, resupply if necessary.
* Return damage if the fortress fires, else -1.
*/
}
/*
- * Fire from ship SP.
+ * Fire from ship @sp.
* Use ammo, resupply if necessary.
* Return damage if the ship fires, else -1.
*/
}
/*
- * Drop depth-charges from ship SP.
+ * Drop depth-charges from ship @sp.
* Use ammo, resupply if necessary.
* Return damage if the ship drops depth-charges, else -1.
*/
}
/*
- * Fire torpedo from ship SP.
+ * Fire torpedo from ship @sp.
* Use ammo and mobility, resupply if necessary.
* Return damage if the ship fires, else -1.
*/
}
/*
- * Fire from land unit LP.
+ * Fire from land unit @lp.
* Use ammo, resupply if necessary.
* Return damage if the land unit fires, else -1.
*/
}
/*
- * Sabotage with land unit LP.
+ * Sabotage with land unit @lp.
* Use ammo.
* Return damage if the land unit sabotages, else -1.
*/
}
/*
- * Return number of guns ship SP can fire.
+ * Return number of guns ship @sp can fire.
*/
int
shp_usable_guns(struct shpstr *sp)
}
/*
- * Return effective firing range for range factor RNG at tech TLEV.
+ * Return effective firing range for range factor @rng at tech @tlev.
*/
static double
effrange(int rng, double tlev)
}
/*
- * Return firing range for sector SP.
+ * Return firing range for sector @sp.
*/
double
fortrange(struct sctstr *sp)
}
/*
- * Return firing range for ship SP.
+ * Return firing range for ship @sp.
*/
double
shp_fire_range(struct shpstr *sp)
}
/*
- * Return torpedo range for ship SP.
+ * Return torpedo range for ship @sp.
*/
double
torprange(struct shpstr *sp)
}
/*
- * Return hit chance for torpedo from ship SP at range RANGE.
+ * Return hit chance for torpedo from ship @sp at range @range.
*/
double
shp_torp_hitchance(struct shpstr *sp, int range)
}
/*
- * Return firing range for land unit SP.
+ * Return firing range for land unit @sp.
*/
double
lnd_fire_range(struct lndstr *lp)
}
/*
- * Append LP to LIST.
+ * Append @lp to @list.
* Return the new list link.
*/
struct ulist *
}
/*
- * Sweep landmines with engineers in LAND_LIST for ACTOR.
- * All land units in LAND_LIST must be in the same sector.
- * If EXPLICIT is non-zero, this is for an explicit sweep command from
+ * Sweep landmines with engineers in @land_list for @actor.
+ * All land units in @land_list must be in the same sector.
+ * If @explicit is non-zero, this is for an explicit sweep command from
* a player. Else it's an automatic "on the move" sweep.
- * If TAKEMOB is non-zero, require and charge mobility.
+ * If @takemob is non-zero, require and charge mobility.
* Return non-zero when the land units should stop.
*/
int
/*
* Ask user to confirm sector abandonment, if any.
- * All land units in LIST must be in the same sector.
- * If removing the land units in LIST would abandon their sector, ask
+ * All land units in @list must be in the same sector.
+ * If removing the land units in @list would abandon their sector, ask
* the user to confirm.
* Return zero when abandonment was declined, else non-zero.
*/
}
/*
- * Fire land unit support against VICTIM for ATTACKER, at X,Y.
- * If DEFENDING, this is defensive support, else offensive support.
+ * Fire land unit support against @victim for @attacker, at @x,@y.
+ * If @defending, this is defensive support, else offensive support.
* Return total damage.
*/
int
}
/*
- * Increase fortification value of LP.
- * Fortification costs mobility. Use up to MOB mobility.
+ * Increase fortification value of @lp.
+ * Fortification costs mobility. Use up to @mob mobility.
* Return actual fortification increase.
*/
int
}
/*
- * Is there a engineer unit at X,Y that can help nation CN?
+ * Is there a engineer unit at @x,@y that can help nation @cn?
*/
static int
has_helpful_engineer(coord x, coord y, natid cn)
}
/*
- * Set LP's tech to TLEV along with everything else that depends on it.
+ * Set @lp's tech to @tlev along with everything else that depends on it.
*/
void
lnd_set_tech(struct lndstr *lp, int tlev)
static int findlost(int, natid, int, coord, coord, int);
/*
- * Record item ID of type TYPE changed owner from EXOWN to OWN at X, Y.
+ * Record item @id of type @type changed owner from @exown to @own at @x, @y.
*/
void
lost_and_found(int type, natid exown, natid own, int id, coord x, coord y)
/*
* Find a suitable slot in the lost file.
- * If a record for TYPE, OWNER, ID, X, Y exists, return its index.
- * Else if FREE is non-zero, return the index of an unused record.
+ * If a record for @type, @owner, @id, @x, @y exists, return its index.
+ * Else if @free is non-zero, return the index of an unused record.
* Else return -1.
*/
static int
}
/*
- * Return character to use in maps for sector type TYPE owned by OWN.
- * If OWNER_OR_GOD, the map is for the sector's owner or a deity.
+ * Return character to use in maps for sector type @type owned by @own.
+ * If @owner_or_god, the map is for the sector's owner or a deity.
*/
static char
map_char(int type, natid own, int owner_or_god)
}
/*
- * Perform support missions in X,Y against VICTIM for ACTEE.
- * MISSION is either MI_OSUPPORT or MI_DSUPPORT.
+ * Perform support missions in @x,@y against @victim for @actee.
+ * @mission is either MI_OSUPPORT or MI_DSUPPORT.
* Return total damage.
*/
static int
}
/*
- * Maximum distance GP can perform its mission.
+ * Maximum distance @gp can perform its mission.
* Note: this has nothing to do with the radius of the op-area.
* oprange() governs where the unit *can* strike, the op-area governs
* where the player wants it to strike.
}
/*
- * Does GP's mission op area cover X,Y?
+ * Does @gp's mission op area cover @x,@y?
*/
int
in_oparea(struct empobj *gp, coord x, coord y)
#include "prototypes.h"
/*
- * Search for COMMAND in COMS[], return its index.
+ * Search for @command in @coms[], return its index.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several, M_IGNORE if the command should be ignored.
- * Ignore commands that require more permissions than COMSTAT.
+ * Ignore commands that require more permissions than @comstat.
*/
int
comtch(char *command, struct cmndstr *coms, int comstat)
/*
* Get nation argument.
- * If ARG is not empty, use it, else prompt for input using PROMPT.
+ * If @arg is not empty, use it, else prompt for input using @prompt.
* If no input is provided, return NULL.
* If the argument identifies a country, return its getnatp() value.
* Else complain and return NULL.
/*
* Get nation argument.
- * If ARG is not empty, use it, else prompt for input using PROMPT.
+ * If @arg is not empty, use it, else prompt for input using @prompt.
* If no input is provided, return -1.
* If the argument identifies a country, return its number. getnatp()
* can be assumed to succeed for this number.
static int nstr_optype(enum nsc_type, enum nsc_type);
/*
- * Compile conditions into array NP[LEN].
+ * Compile conditions into array @np[@len].
* Return number of conditions, or -1 on error.
- * It is an error if there are more than LEN conditions.
- * TYPE is the context type, a file type.
- * STR is the condition string, in Empire syntax, without the leading
+ * It is an error if there are more than @len conditions.
+ * @type is the context type, a file type.
+ * @str is the condition string, in Empire syntax, without the leading
* '?'.
*/
int
: (CANT_REACH(), 0))
/*
- * Evaluate compiled conditions in array NP[NCOND].
+ * Evaluate compiled conditions in array @np[@ncond].
* Return non-zero iff they are all true.
- * PTR points to a context object of the type that was used to compile
+ * @ptr points to a context object of the type that was used to compile
* the conditions.
*/
int
}
/*
- * Parse a value in STR into VAL.
+ * Parse a value in @str into @val.
* Return a pointer to the first character after the value.
* Value is either evaluated into NSC_STRING, NSC_DOUBLE or NSC_LONG,
* or an identifier.
}
/*
- * Match VAL in table of selector descriptors CA, return index.
+ * Match @val in table of selector descriptors @ca, return index.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several.
- * A VAL that is not an identifier doesn't match anything. A null CA
+ * A @val that is not an identifier doesn't match anything. A null @ca
* is considered empty.
*/
static int
}
/*
- * Is identifier VAL the name of the selector given by CA and IDX?
- * Return non-zero if and only if IDX is non-negative and VAL is the
- * name of CA[IDX].
- * IDX must have been obtained from nstr_match_ca(VAL, CA).
+ * Is identifier @val the name of the selector given by @ca and @idx?
+ * Return non-zero if and only if @idx is non-negative and @val is the
+ * name of @ca[@idx].
+ * @idx must have been obtained from nstr_match_ca(@val, @ca).
*/
static int
nstr_is_name_of_ca(struct valstr *val, struct castr *ca, int idx)
/*
* Do we have two comparable selectors?
- * Check selector descriptors CA[LFT_IDX] (unless LFT_IDX is negative)
- * and CA[RGT_IDX] (unless RGT_IDX is negative). CA may be null when
+ * Check selector descriptors @ca[@lft_idx] (unless @lft_idx is negative)
+ * and @ca[@rgt_idx] (unless @rgt_idx is negative). @ca may be null when
* both are negative.
*/
static int
}
/*
- * Match VAL in a selector's values, return its (non-negative) value.
- * Match values of selector descriptor CA[IDX], provided IDX is not
- * negative. CA may be null when IDX is negative.
+ * Match @val in a selector's values, return its (non-negative) value.
+ * Match values of selector descriptor @ca[@idx], provided @idx is not
+ * negative. @ca may be null when @idx is negative.
* Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
* several.
*/
}
/*
- * Change VAL to resolve identifier to selector.
- * Return VAL on success, NULL on error.
- * No change if VAL is not an identifier.
- * Else change VAL into symbolic value for selector CA[IDX] if IDX >=
+ * Change @val to resolve identifier to selector.
+ * Return @val on success, NULL on error.
+ * No change if @val is not an identifier.
+ * Else change @val into symbolic value for selector @ca[@idx] if @idx >=
* 0, and error if not.
*/
static struct valstr *
}
/*
- * Change VAL to resolve identifier to value SELVAL for selector CA.
- * Return VAL.
- * VAL must be an identifier, and SELVAL must have been obtained from
- * nstr_match_val(VAL, CA0, IDX), where CA = &CA0[IDX].
+ * Change @val to resolve identifier to value @selval for selector @ca.
+ * Return @val.
+ * @val must be an identifier, and @selval must have been obtained from
+ * nstr_match_val(@val, CA0, @idx), where @ca = &CA0[@IDX].
*/
static struct valstr *
nstr_resolve_val(struct valstr *val, int selval, struct castr *ca)
}
/*
- * Return operator type for operand types LFT, RGT.
+ * Return operator type for operand types @lft, @rgt.
*/
static int
nstr_optype(enum nsc_type lft, enum nsc_type rgt)
}
/*
- * Compile a value in STR into VAL.
+ * Compile a value in @str into @val.
* Return a pointer to the first character after the value on success,
* NULL on error.
- * TYPE is the context type, a file type.
+ * @type is the context type, a file type.
*/
char *
nstr_comp_val(char *str, struct valstr *val, int type)
}
/*
- * Map direction DIR to a direction index DIR_STOP..DIR_LAST.
- * DIR must be a valid direction.
+ * Map direction @dir to a direction index DIR_STOP..DIR_LAST.
+ * @dir must be a valid direction.
*/
int
diridx(char dir)
/*
* Get planes and escorts argument.
- * Read planes into *NI_BOMB, and (optional) escorts into *NI_ESC.
- * If INPUT_BOMB is not empty, use it, else prompt for more input.
- * Same for INPUT_ESC.
- * If we got a plane argument, initialize *NI_BOMB and *NI_ESC, and
+ * Read planes into *@ni_bomb, and (optional) escorts into *@ni_esc.
+ * If @input_bomb is not empty, use it, else prompt for more input.
+ * Same for @input_esc.
+ * If we got a plane argument, initialize *@ni_bomb and *@ni_esc, and
* return 0.
- * Else return -1 (*NI_BOMB and *NI_ESC may be modified).
+ * Else return -1 (*@ni_bomb and *@ni_esc may be modified).
*/
int
get_planes(struct nstr_item *ni_bomb, struct nstr_item *ni_esc,
/*
* Get assembly point argument.
- * If INPUT is not empty, use it, else prompt for more input using PROMPT.
- * If this yields a valid assembly point, read it into *AP_SECT and
- * return AP_SECT.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
+ * If this yields a valid assembly point, read it into *@ap_sect and
+ * return @ap_sect.
* Else complain and return NULL.
- * *AP_SECT and BUF[1024] may be modified in either case.
+ * *@ap_sect and @buf[1024] may be modified in either case.
*/
struct sctstr *
get_assembly_point(char *input, struct sctstr *ap_sect, char *buf)
}
/*
- * Find out whether planes can fly one-way to X,Y.
+ * Find out whether planes can fly one-way to @x,@y.
* Offer the player any carriers there. If he chooses one, read it
- * into TARGET->ship. Else read the target sector into TARGET->sect.
- * If planes can land there, set required plane flags in *FLAGSP, and
+ * into @target->ship. Else read the target sector into @target->sect.
+ * If planes can land there, set required plane flags in *@flagsp, and
* return 0. Else return -1.
*/
int
}
/*
- * Has PP's type capabilities satisfying WANTFLAGS and NOWANTFLAGS?
+ * Has @pp's type capabilities satisfying @wantflags and @nowantflags?
* A plane type is capable unless
- * - it lacks all of the P_B, P_T in WANTFLAGS, or
- * - it lacks all of the P_F, P_ESC in WANTFLAGS, or
- * - it lacks all of the P_E, P_L, P_K in WANTFLAGS, or
- * - it lacks any of the other capabilities in WANTFLAGS, or
- * - it has any of the capabilities in NOWANTFLAGS.
+ * - it lacks all of the P_B, P_T in @wantflags, or
+ * - it lacks all of the P_F, P_ESC in @wantflags, or
+ * - it lacks all of the P_E, P_L, P_K in @wantflags, or
+ * - it lacks any of the other capabilities in @wantflags, or
+ * - it has any of the capabilities in @nowantflags.
*/
int
pln_capable(struct plnstr *pp, int wantflags, int nowantflags)
}
/*
- * Return union of capabilities of planes in LIST.
+ * Return union of capabilities of planes in @list.
*/
int
pln_caps(struct emp_qelem *list)
}
/*
- * Find plane types that can operate from carrier SP.
- * If MSL find missile types, else non-missile types.
+ * Find plane types that can operate from carrier @sp.
+ * If @msl find missile types, else non-missile types.
* Return a combination of P_L, P_K, P_E.
- * It's zero if SP can't support air operations due to its type or
+ * It's zero if @sp can't support air operations due to its type or
* state (low efficiency).
*/
int
}
/*
- * Can a carrier of SP's type carry this load of planes?
- * The load consists of N planes, of which NCH are choppers, NXL
- * xlight, NMSL light missiles, and the rest are light fixed-wing
+ * Can a carrier of @sp's type carry this load of planes?
+ * The load consists of @n planes, of which @nch are choppers, @nxl
+ * xlight, @nmsl light missiles, and the rest are light fixed-wing
* planes.
*/
static int
}
/*
- * Increment carrier plane counters for PP.
- * If it's a chopper, increment *NCH.
- * Else, if it's x-light, increment *NXL.
- * Else, if it's a light missile, increment *MSL.
+ * Increment carrier plane counters for @pp.
+ * If it's a chopper, increment *@nch.
+ * Else, if it's x-light, increment *@nxl.
+ * Else, if it's a light missile, increment *@msl.
* Return non-zero if it's a chopper, x-light or light.
*/
static int
}
/*
- * Can PP be loaded on a ship of SP's type?
+ * Can @pp be loaded on a ship of @sp's type?
*/
int
could_be_on_ship(struct plnstr *pp, struct shpstr *sp)
}
/*
- * Set PP's tech to TLEV along with everything else that depends on it.
+ * Set @pp's tech to @tlev along with everything else that depends on it.
*/
void
pln_set_tech(struct plnstr *pp, int tlev)
/*
* Print to current player similar to printf().
- * Use printf-style FORMAT with the optional arguments.
+ * Use printf-style @format with the optional arguments.
* Note: `to print' without further qualifications means sending
* C_DATA text.
*/
}
/*
- * Print UTF-8 text BUF to current player.
+ * Print UTF-8 text @buf to current player.
*/
void
uprnf(char *buf)
}
/*
- * Send some text to P with id ID, line-buffered.
- * Format text to send using printf-style FORMAT and optional
+ * Send some text to @p with id @id, line-buffered.
+ * Format text to send using printf-style @format and optional
* arguments. It is assumed to be already user text. Plain ASCII and
* text received from the same player are fine, for anything else the
* caller has to deal with output filtering.
}
/*
- * Send C_FLASH text to PL.
- * Format text to send using printf-style FORMAT and optional
+ * Send C_FLASH text to @pl.
+ * Format text to send using printf-style @format and optional
* arguments. It is assumed to be UTF-8.
* Initiate an output queue flush, but do not wait for it to complete.
*/
}
/*
- * Send C_INFORM text to PL.
- * Format text to send using printf-style FORMAT and optional
+ * Send C_INFORM text to @pl.
+ * Format text to send using printf-style @format and optional
* arguments. It is assumed to be plain ASCII.
* Initiate an output queue flush, but do not wait for it to complete.
*/
/*
* Send C_FLASH text to everyone.
- * Format text to send using printf-style FORMAT and optional
+ * Format text to send using printf-style @format and optional
* arguments. It is assumed to be plain ASCII.
* Prefix text it with a header suitable for broadcast from deity.
* Initiate an output queue flush, but do not wait for it to complete.
}
/*
- * Send ID text BUF to PL, line-buffered.
- * BUF is user text.
+ * Send @id text @buf to @pl, line-buffered.
+ * @buf is user text.
* If a partial line with different id is buffered, terminate it with
* a newline first.
*/
}
/*
- * Send ID text BUF to PL, line-buffered.
+ * Send @id text @buf to @pl, line-buffered.
* This function translates from normal text to user text.
* If a partial line with different id is buffered, terminate it with
* a newline first.
}
/*
- * Send id N to PL.
+ * Send id @n to @pl.
* This runs always at the beginning of a line.
*/
static void
}
/*
- * Send redirection request REDIR to the current player.
- * REDIR is UTF-8, but non-ASCII characters can occur only if the
+ * Send redirection request @redir to the current player.
+ * @redir is UTF-8, but non-ASCII characters can occur only if the
* player sent them. Therefore, it is also user text.
*/
void
}
/*
- * Send script execute request FILE to the current player.
- * FILE is UTF-8, but non-ASCII characters can occur only if the
+ * Send script execute request @file to the current player.
+ * @file is UTF-8, but non-ASCII characters can occur only if the
* player sent them. Therefore, it is also user text.
*/
void
/*
* Prompt for a line of non-command input.
- * Send C_FLUSH prompt PROMPT to the current player.
- * Read a line of input into BUF[SIZE] and convert it to ASCII.
+ * Send C_FLUSH prompt @prompt to the current player.
+ * Read a line of input into @buf[@size] and convert it to ASCII.
* This may block for input, yielding the processor. Flush buffered
* output when blocking, to make sure player sees the prompt.
- * Return number of bytes in BUF[], not counting the terminating 0,
+ * Return number of bytes in @buf[], not counting the terminating 0,
* or -1 on error.
*/
int
/*
* Prompt for a line of non-command, UTF-8 input.
- * Send C_FLUSH prompt PROMPT to the current player.
- * Read a line of input into BUF[SIZE], replacing funny characters by
+ * Send C_FLUSH prompt @prompt to the current player.
+ * Read a line of input into @buf[@size], replacing funny characters by
* '?'. The result is UTF-8.
* This may block for input, yielding the processor. Flush buffered
* output when blocking, to make sure player sees the prompt.
- * Return number of bytes in BUF[], not counting the terminating 0,
+ * Return number of bytes in @buf[], not counting the terminating 0,
* or -1 on error.
*/
int
}
/*
- * Print coordinates X, Y.
- * FORMAT must be a printf-style format string that converts exactly
+ * Print coordinates @x, @y.
+ * @format must be a printf-style format string that converts exactly
* two int values.
*/
void
}
/*
- * Print complete lines to country CN similar to printf().
- * Use printf-style FORMAT with the optional arguments. FORMAT must
+ * Print complete lines to country @cn similar to printf().
+ * Use printf-style @format with the optional arguments. @format must
* end with '\n'.
- * If CN is zero, don't print anything.
- * Else, if CN is the current player and we're not in the update,
+ * If @cn is zero, don't print anything.
+ * Else, if @cn is the current player and we're not in the update,
* print just like pr(). Else print into a bulletin.
* Because printing like pr() requires normal text, and bulletins
* require user text, only plain ASCII is allowed.
}
/*
- * Copy SRC without funny characters to DST.
+ * Copy @src without funny characters to @dst.
* Drop control characters, except for '\t'.
* Replace non-ASCII characters by '?'.
- * Return length of DST.
- * DST must have space. If it overlaps SRC, then DST <= SRC must
+ * Return length of @dst.
+ * @dst must have space. If it overlaps @src, then @dst <= @src must
* hold.
*/
size_t
}
/*
- * Copy UTF-8 SRC without funny characters to DST.
+ * Copy UTF-8 @src without funny characters to @dst.
* Drop control characters, except for '\t'.
* FIXME Replace malformed UTF-8 sequences by '?'.
- * Return byte length of DST.
- * DST must have space. If it overlaps SRC, then DST <= SRC must
+ * Return byte length of @dst.
+ * @dst must have space. If it overlaps @src, then @dst <= @src must
* hold.
*/
size_t
}
/*
- * Copy UTF-8 SRC without funny characters to ASCII DST.
+ * Copy UTF-8 @src without funny characters to ASCII @dst.
* Drop control characters, except for '\t'.
* Replace non-ASCII characters by '?'.
- * Return length of DST.
- * DST must have space. If it overlaps SRC, then DST <= SRC must
+ * Return length of @dst.
+ * @dst must have space. If it overlaps @src, then @dst <= @src must
* hold.
*/
size_t
}
/*
- * Return byte-index of the N-th UTF-8 character in UTF-8 string S.
- * If S doesn't have that many characters, return its length instead.
+ * Return byte-index of the @n-th UTF-8 character in UTF-8 string @s.
+ * If @s doesn't have that many characters, return its length instead.
*/
int
ufindpfx(char *s, int n)
static signed char *visbuf;
/*
- * Draw a radar map for radar at CX,CY.
- * EFF is the radar's efficiency, TLEV its tech level, SPY its power.
- * Submarines are detected at fraction SEESUB of the range.
+ * Draw a radar map for radar at @cx,@cy.
+ * @eff is the radar's efficiency, @tlev its tech level, @spy its power.
+ * Submarines are detected at fraction @seesub of the range.
*/
void
radmap(int cx, int cy, int eff, double tlev, int spy, double seesub)
}
/*
- * Return distance from left edge of R to X.
+ * Return distance from left edge of @r to @x.
* Value is between 0 (inclusive) and WORLD_X (exclusive).
- * X must be normalized.
+ * @x must be normalized.
*/
int
deltx(struct range *r, coord x)
}
/*
- * Return distance from top edge of R to Y.
+ * Return distance from top edge of @r to @y.
* Value is between 0 (inclusive) and WORLD_Y (exclusive).
- * Y must be normalized.
+ * @y must be normalized.
*/
int
delty(struct range *r, coord y)
}
/*
- * Update OWNER's bmap for radar at CX,CY.
- * EFF is the radar's efficiency, TLEV its tech level, SPY its power.
+ * Update @owner's bmap for radar at @cx,@cy.
+ * @eff is the radar's efficiency, @tlev its tech level, @spy its power.
*/
void
rad_map_set(natid owner, int cx, int cy, int eff, double tlev, int spy)
}
/*
- * Range of a radar with EFF efficiency, TLEV tech, and SPY power.
+ * Range of a radar with @eff efficiency, @tlev tech, and @spy power.
*/
static int
rad_range(int eff, double tlev, int spy)
}
/*
- * Return character to use in radar maps for sector SP.
- * DIST is the distance from the radar, RANGE its range.
- * Country CN is using the radar.
+ * Return character to use in radar maps for sector @SP.
+ * @dist is the distance from the radar, @range its range.
+ * Country @cn is using the radar.
*/
static char
rad_char(struct sctstr *sp, int dist, int range, natid cn)
}
/*
- * Return T formatted according to RFC 2822.
+ * Return @t formatted according to RFC 2822.
* The return value is statically allocated and overwritten on
* subsequent calls.
*/
}
/*
- * Append SP to LIST.
+ * Append @sp to @list.
* Return the new list link.
*/
struct ulist *
}
/*
- * Sweep seamines with engineers in SHIP_LIST for ACTOR.
- * All ships in SHIP_LIST must be in the same sector.
- * If EXPLICIT is non-zero, this is for an explicit sweep command from
+ * Sweep seamines with engineers in @ship_list for @actor.
+ * All ships in @ship_list must be in the same sector.
+ * If @explicit is non-zero, this is for an explicit sweep command from
* a player. Else it's an automatic "on the move" sweep.
- * If TAKEMOB is non-zero, require and charge mobility.
+ * If @takemob is non-zero, require and charge mobility.
* Return non-zero when the ships should stop.
*/
int
}
/*
- * Return whether and why SP would be stuck in SECTP.
+ * Return whether and why @sp would be stuck in @sectp.
*/
enum shp_stuck
shp_check_nav(struct shpstr *sp, struct sctstr *sectp)
}
/*
- * Set SP's tech to TLEV along with everything else that depends on it.
+ * Set @sp's tech to @tlev along with everything else that depends on it.
*/
void
shp_set_tech(struct shpstr *sp, int tlev)
}
/*
- * Initialize NP to iterate over the items of type TYPE in a carrier.
- * The carrier has file type CARRIER_TYPE and uid CARRIER_UID.
+ * Initialize @np to iterate over the items of type @type in a carrier.
+ * The carrier has file type @carrier_type and uid @carrier_uid.
* Note: you can take an item gotten with nxtitem() off its carrier
* without disturbing the iterator. Whether the iterator will pick up
* stuff you load onto the carrier during iteration is unspecified.
}
/*
- * Return amount due for LOAN at time PAYTIME.
+ * Return amount due for @loan at time @paytime.
*/
double
loan_owed(struct lonstr *loan, time_t paytime)
}
/*
- * Teleport UNIT to X,Y.
- * If UNIT's mission op-area is centered on it, keep it centered.
+ * Teleport @unit to @x,@y.
+ * If @unit's mission op-area is centered on it, keep it centered.
*/
void
unit_teleport(struct empobj *unit, coord x, coord y)
}
/*
- * Update cargo of CARRIER for movement or destruction.
+ * Update cargo of @carrier for movement or destruction.
* If the carrier is destroyed, destroy its cargo (planes, land units,
* nukes).
* Else update their location to the carrier's. Any op sectors equal
}
/*
- * Drop cargo of UNIT.
- * Give it to NEWOWN, unless it's zero.
+ * Drop cargo of @unit.
+ * Give it to @newown, unless it's zero.
*/
void
unit_drop_cargo(struct empobj *unit, natid newown)
}
/*
- * Give UNIT and its cargo to RECIPIENT.
- * No action if RECIPIENT already owns UNIT.
- * If GIVER is non-zero, inform RECIPIENT and GIVER of the transaction.
+ * Give @unit and its cargo to @recipient.
+ * No action if @recipient already owns @unit.
+ * If @giver is non-zero, inform @recipient and @giver of the transaction.
* Clears mission and group on the units given away.
*/
void
}
/*
- * Wipe orders and such from UNIT.
+ * Wipe orders and such from @unit.
*/
void
unit_wipe_orders(struct empobj *unit)
/*
* Get item type argument.
- * If INPUT is not empty, use it, else prompt for more input using PROMPT.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
* Return item characteristics on success, else NULL.
*/
struct ichrstr *
}
/*
- * Map item type name STR to item characteristics, NULL if not found.
+ * Map item type name @str to item characteristics, NULL if not found.
*/
struct ichrstr *
item_by_name(char *str)
}
/*
- * Send a telegram from FROM to TO.
- * Format text to send using printf-style FORMAT and optional
+ * Send a telegram from @from to @to.
+ * Format text to send using printf-style @format and optional
* arguments. It is plain ASCII.
* If running from the update, telegram type is TEL_UPDATE.
- * Else if FROM is a deity, type is TEL_BULLETIN.
+ * Else if @from is a deity, type is TEL_BULLETIN.
* Else it is TEL_NORM.
* Return 0 on success, -1 on error.
*/
}
/*
- * Send a telegram from FROM to TO.
- * MESSAGE is the text to send, in UTF-8.
- * TYPE is the telegram type.
+ * Send a telegram from @from to @to.
+ * @message is the text to send, in UTF-8.
+ * @type is the telegram type.
* Return 0 on success, -1 on error.
*/
int
}
/*
- * Return the item value tracked in BP for sector SP's item COMM.
- * COMM must be a tracked item type.
+ * Return the item value tracked in @bp for sector @sp's item @comm.
+ * @comm must be a tracked item type.
*/
int
bp_get_item(struct bp *bp, struct sctstr *sp, i_type comm)
return bp_ref(bp, sp)->bp_item[idx];
}
-/* Set the item value tracked in BP for sector SP's item COMM. */
+/* Set the item value tracked in @bp for sector @sp's item @comm. */
void
bp_put_item(struct bp *bp, struct sctstr *sp, i_type comm, int amount)
{
bp_ref(bp, sp)->bp_item[idx] = amount;
}
-/* Set the item values tracked in BP for sector SP from VEC. */
+/* Set the item values tracked in @bp for sector @sp from @vec. */
void
bp_put_items(struct bp *bp, struct sctstr *sp, short *vec)
{
}
}
-/* Return avail tracked in BP for sector SP. */
+/* Return avail tracked in @bp for sector @sp. */
int
bp_get_avail(struct bp *bp, struct sctstr *sp)
{
return bp_ref(bp, sp)->bp_avail;
}
-/* Set avail tracked in BP for sector SP. */
+/* Set avail tracked in @bp for sector @sp. */
void
bp_put_avail(struct bp *bp, struct sctstr *sp, int amount)
{
bp_ref(bp, sp)->bp_avail = amount;
}
-/* Set the values tracked in BP for sector SP to the values in SP. */
+/* Set the values tracked in @bp for sector @sp to the values in @sp. */
void
bp_set_from_sect(struct bp *bp, struct sctstr *sp)
{
}
/*
- * Return food eaten by people in VEC[] in ETU ETUs.
+ * Return food eaten by people in @vec[] in @etu ETUs.
*/
double
food_needed(short *vec, int etu)
}
/*
- * Return number of famine victims in VEC[] for ETU ETUs.
+ * Return number of famine victims in @vec[] for @etu ETUs.
*/
int
famine_victims(short *vec, int etu)
}
/*
- * Starve up to NUM people of VEC[WHOM].
+ * Starve up to @num people of @vec[@whom].
* Return the number of actually starved.
*/
static int
}
/*
- * Return the number of babies born to ADULTS in ETU ETUs.
- * BRATE is the birth rate.
- * FOOD is the food available for growing babies.
- * MAXPOP is the population limit.
+ * Return the number of babies born to @adults in @etu ETUs.
+ * @brate is the birth rate.
+ * @food is the food available for growing babies.
+ * @maxpop is the population limit.
*/
static int
babies(int adults, int etu, double brate, int food, int maxpop)
#include "update.h"
/*
- * Get build materials from sector SP.
- * BP is the sector's build pointer.
- * MVEC[] defines the materials needed to build 100%.
- * PCT is the percentage to build.
+ * Get build materials from sector @sp.
+ * @bp is the sector's build pointer.
+ * @mvec[] defines the materials needed to build 100%.
+ * @pct is the percentage to build.
* Adjust build percentage downwards so that available materials
* suffice. Remove the materials.
* Return adjusted build percentage.
}
/*
- * Return how much of product PP can be made from materials VEC[].
- * Store amount of work per unit in *COSTP.
+ * Return how much of product @pp can be made from materials @vec[].
+ * Store amount of work per unit in *@costp.
*/
int
prod_materials_cost(struct pchrstr *pp, short vec[], int *costp)
}
/*
- * Return how much of product PP can be made from its resource.
- * If PP depletes a resource, RESOURCE must point to its value.
+ * Return how much of product @pp can be made from its resource.
+ * If @pp depletes a resource, @resource must point to its value.
*/
int
prod_resource_limit(struct pchrstr *pp, unsigned char *resource)
}
/*
- * Return p.e. for sector type TYPE.
+ * Return p.e. for sector type @type.
* Zero means level is too low for production.
- * LEVEL is the affecting production of PP; it must match PP->p_nlndx.
+ * @level is the affecting production of PP; it must match PP->p_nlndx.
*/
double
prod_eff(int type, float level)
}
/*
- * Do fallout meltdown for sector SP.
- * ETUS above 24 are treated as 24 to avoid *huge* kill offs in
+ * Do fallout meltdown for sector @sp.
+ * @etus above 24 are treated as 24 to avoid *huge* kill offs in
* large ETU games.
*/
void
static void shutdown_sequence(void *unused);
/*
- * Initiate shutdown in MINS_FROM_NOW minutes.
- * If MINS_FROM_NOW is negative, cancel any pending shutdown instead.
+ * Initiate shutdown in @mins_from_now minutes.
+ * If @mins_from_now is negative, cancel any pending shutdown instead.
* Return -1 on error, zero when no shutdown was pending, positive
* number when a pending shutdown was modified.
*/
projects / empserver / commitdiff