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

16
src/lib/commands/flash.c
View file

@ -79,9 +79,9 @@ wall(void)
}
/*
* 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
@ -107,11 +107,11 @@ chat(struct natstr *to, char *message)
}
/*
* 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)

4
src/lib/commands/laun.c
View file

@ -124,7 +124,7 @@ laun(void)
}
/*
* 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.
*/
@ -169,7 +169,7 @@ launch_as(struct plnstr *pp)
}
/*
* Launch missile PP.
* Launch missile @pp.
* Return RET_OK if launched (even when missile explodes),
* else RET_SYN or RET_FAIL.
*/

2
src/lib/commands/rea.c
View file

@ -193,7 +193,7 @@ rea(void)
}
/*
* Print first telegram in file FNAME.
* Print first telegram in file @fname.
*/
int
show_first_tel(char *fname)

8
src/lib/commands/xdump.c
View file

@ -39,7 +39,7 @@
#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
@ -99,8 +99,8 @@ xdvisible(int type, void *p)
}
/*
* 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)
@ -131,7 +131,7 @@ 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