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

56
src/lib/common/xdump.c
View file

@ -80,13 +80,13 @@
#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,
@ -101,11 +101,11 @@ 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,
@ -116,8 +116,8 @@ 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)
@ -140,8 +140,8 @@ 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 *
@ -175,8 +175,8 @@ xdprval_nosym(struct xdstr *xd, struct valstr *val, char *sep)
}
/*
* 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)
@ -194,9 +194,9 @@ 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,
@ -228,9 +228,9 @@ 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)
@ -254,8 +254,8 @@ 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)
@ -269,9 +269,9 @@ 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[])