empire/empserver
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Change comment style to use @foo rather than FOO

Browse source 
... when referring to a function's parameter or a struct/union's
member.

The idea of using FOO comes from the GNU coding standards:

    The comment on a function is much clearer if you use the argument
    names to speak about the argument values.  The variable name
    itself should be lower case, but write it in upper case when you
    are speaking about the value rather than the variable itself.
    Thus, "the inode number NODE_NUM" rather than "an inode".

Upcasing names is problematic for a case-sensitive language like C,
because it can create ambiguity.  Moreover, it's too much shouting for
my taste.

GTK-Doc's convention to prefix the identifier with @ makes references
to variables stand out nicely.  The rest of the GTK-Doc conventions
make no sense for us, however.

Signed-off-by: Markus Armbruster <armbru@pond.sub.org>
This commit is contained in:
Markus Armbruster 2015-06-14 10:33:43 +02:00
parent 5cff5022a9
commit 9f25de3dce
77 changed files with 633 additions and 633 deletions
Download patch file Download diff file Expand all files Collapse all files

46
include/empthread.h
View file

@ -101,8 +101,8 @@ void empth_request_shutdown(void);
/*
* 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.
*/
@ -110,12 +110,12 @@ int empth_init(void **ctx, int flags);
/*
* 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.
@ -131,12 +131,12 @@ empth_t *empth_create(void (*entry)(void *),
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);
@ -155,27 +155,27 @@ void empth_exit(void);
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().
*/
@ -189,18 +189,18 @@ int empth_wait_for_signal(void);
/*
* 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.
@ -208,7 +208,7 @@ void empth_rwlock_destroy(empth_rwlock_t *rwlock);
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
@ -217,8 +217,8 @@ void empth_rwlock_wrlock(empth_rwlock_t *rwlock);
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);

8
include/map.h
View file

@ -36,15 +36,15 @@
#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).
*

4
include/misc.h
View file

@ -60,8 +60,8 @@
#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)

24
include/nsc.h
View file

@ -86,10 +86,10 @@ enum nsc_cat {
* 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
@ -180,7 +180,7 @@ struct nstr_item {
};
/*
* Symbol binding: associate NAME with VALUE.
* Symbol binding: associate @name with @value.
*/
struct symbol {
int value;
@ -200,16 +200,16 @@ enum {
* 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.
@ -224,8 +224,8 @@ enum {
* 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.
*/