Restored retval docs.

src/act.movement.c

@@ -123,7 +123,9 @@ static int has_scuba(struct char_data *ch)
  * @param ch The character structure to attempt to move.
  * @param dir The defined direction (NORTH, SOUTH, etc...) to attempt to
  * move into.
- * @param need_specials_check If TRUE will cause */
+ * @param need_specials_check If TRUE will cause 
+ * @retval int 1 for a successful move (ch is now in a new location)		
+ * or 0 for a failed move (ch is still in the original location). */
 int do_simple_move(struct char_data *ch, int dir, int need_specials_check)
 {
   /* Begin Local variable definitions */

src/dg_event.c

@@ -52,7 +52,8 @@ void event_init(void)
  * event fires. It is func's job to cast event_obj. If event_obj is not needed,
  * pass in NULL.
  * @param when Number of pulses between firing(s) of this event.
- * */
+ * @retval event * Returns a pointer to the newly created event.
+ **/
 struct event *event_create(EVENTFUNC(*func), void *event_obj, long when)
 {
   struct event *new_event;
@@ -136,7 +137,8 @@ void event_process(void)
 }
 
 /** Returns the time remaining before the event as how many pulses from now. 
- * @param event Check this event for it's scheduled activation time. */
+ * @param event Check this event for its scheduled activation time.
+ * @retval long Number of pulses before this event will fire. */
 long event_time(struct event *event)
 {
   long when;
@@ -153,7 +155,9 @@ void event_free_all(void)
 }
 
 /** Boolean function to tell whether an event is queued or not. Does this by
- * checking if event->q_el points to anything but null. */
+ * checking if event->q_el points to anything but null.
+ * @retval int 1 if the event has been queued, 0 if the event has not.
+ **/
 int event_is_queued(struct event *event)
 {
    if (event->q_el)
@@ -168,7 +172,8 @@ int event_is_queued(struct event *event)
 /***************************************************************************
  * Begin generic (abstract) priority queue functions
  **************************************************************************/
-/** Create a new, empty, priority queue and return it. */
+/** Create a new, empty, priority queue and return it.
+ * @retval dg_queue * Pointer to the newly created queue structure. */
 struct dg_queue *queue_init(void)
 {
   struct dg_queue *q;
@@ -185,7 +190,9 @@ struct dg_queue *queue_init(void)
  * @param data The data to be associated with, and theoretically used, when
  * the element comes up in q. data is wrapped in a new q_element.
  * @param key Indicates where this event should be located in the queue, and
- * when the element should be activated. */
+ * when the element should be activated.
+ * @retval q_element Pointer to the created q_element that contains
+ * the data. */
 struct q_element *queue_enq(struct dg_queue *q, void *data, long key)
 {
   struct q_element *qe, *i;
@@ -260,7 +267,9 @@ void queue_deq(struct dg_queue *q, struct q_element *qe)
  * @pre pulse must be defined. This is a multi-headed queue, the current
  * head is determined by the current pulse.
  * @post the q->head is dequeued. 
- * @param q The queue to return the head of. */
+ * @param q The queue to return the head of.
+ * @retval void * NULL if there is not a currently available head, pointer
+ * to any data object associated with the queue element. */
 void *queue_head(struct dg_queue *q)
 {
   void *dg_data;
@@ -279,7 +288,9 @@ void *queue_head(struct dg_queue *q)
 /** Returns the key of the head element of the priority queue.
  * @pre pulse must be defined. This is a multi-headed queue, the current
  * head is determined by the current pulse. 
- * @param q Queue to check for. */
+ * @param q Queue to check for.
+ * @retval long Return the key element of the head q_element. If no head
+ * q_element is available, return LONG_MAX. */
 long queue_key(struct dg_queue *q)
 {
   int i;
@@ -293,7 +304,8 @@ long queue_key(struct dg_queue *q)
 }
 
 /** Returns the key of queue element qe.
- * @param qe Pointer to the keyed q_element. */
+ * @param qe Pointer to the keyed q_element.
+ * @retval long Key of qe. */
 long queue_elmt_key(struct q_element *qe)
 {
   return qe->key;

src/dg_scripts.c

@@ -81,7 +81,9 @@ static EVENTFUNC(trig_wait_event);
  * a match.
  * @todo Move this function to string util library.
  * @param cs The string to search.
- * @param ct What to search for in cs. */
+ * @param ct What to search for in cs.
+ * @retval char * NULL if ct is not a substring of cs, or pointer to the
+ * location in cs where substring ct begins. */
 char *str_str(char *cs, char *ct)
 {
   char *s, *t;
@@ -112,7 +114,9 @@ char *str_str(char *cs, char *ct)
 }
 
 /** Returns the number of people in a room.
- * @param vnum The virtual number of a room. */
+ * @param vnum The virtual number of a room.
+ * @retval int Returns -1 if the room does not exist, or the total number of
+ * PCs and NPCs in the room. */
 int trgvar_in_room(room_vnum vnum) 
 {
     room_rnum rnum = real_room(vnum);
@@ -135,6 +139,8 @@ int trgvar_in_room(room_vnum vnum)
  * @param name Either the unique id of an object or a string identifying the
  * object. Note the unique id must be prefixed with UID_CHAR.
  * @param list The list of objects to look through.
+ * @retval obj_data * Pointer to the object if it is found in the list of
+ * objects, NULL if the object is not found in the list.
  */
 obj_data *get_obj_in_list(char *name, obj_data *list)
 {
@@ -161,6 +167,8 @@ obj_data *get_obj_in_list(char *name, obj_data *list)
  * @param ch Pointer to the NPC/PC to search through.
  * @param name String describing either the name of the object or the unique
  * id of the object. Note the unique id must be prefixed with UID_CHAR.
+ * @retval obj_data * Either a pointer to the first object found that matches
+ * the name argument, or the NULL if the object isn't found.
  */
 obj_data *get_object_in_equip(char_data * ch, char *name)
 {
@@ -203,6 +211,8 @@ obj_data *get_object_in_equip(char_data * ch, char *name)
  * Byron Ellacott. 
  * @param arg Either the name of the position, or the number of a wear
  * location definition to check for.
+ * @retval int If arg is not a valid wear location name or number, return
+ * -1, else return the defined number of the wear location.
  */
 int find_eq_pos_script(char *arg)
 {
@@ -246,6 +256,7 @@ int find_eq_pos_script(char *arg)
 /** Figures out if an object can be worn on a defined wear location.
  * @param obj The object to check.
  * @param pos The defined wear location to check.
+ * @retval int TRUE if obj can be worn on pos, FALSE if not.
  */
 int can_wear_on_pos(struct obj_data *obj, int pos)
 {
@@ -274,6 +285,8 @@ int can_wear_on_pos(struct obj_data *obj, int pos)
 
 /** Search for an NPC or PC by number routines.
  * @param n The unique ID (PC or NPC) to look for.
+ * @retval char_data * Pointer to the character structure if it exists, or NULL
+ * if it cannot be found.
  */
 struct char_data *find_char(long n)
 {
@@ -285,6 +298,8 @@ struct char_data *find_char(long n)
 
 /** Search for an object by number routines.
  * @param n The unique ID to look for.
+ * @retval obj_data * Pointer to the object if it exists, or NULL if it cannot
+ * be found.
  */
 static obj_data *find_obj(long n)
 {
@@ -296,6 +311,8 @@ static obj_data *find_obj(long n)
 
 /* Search for a room with UID n.
  * @param n the Unique ID to look for.
+ * @retval room_data * Pointer to the room if it exists, or NULL if it cannot
+ * be found.
  */
 static room_data *find_room(long n)
 {
@@ -315,7 +332,8 @@ static room_data *find_room(long n)
 /* Generic searches based only on name. */
 /** Search the entire world for an NPC or PC by name. 
  * @param name String describing the name or the unique id of the char. 
- * Note the unique id must be prefixed with UID_CHAR. */
+ * Note the unique id must be prefixed with UID_CHAR.
+ * @retval char_data * Pointer to the char or NULL if char is not found. */
 char_data *get_char(char *name)
 {
   char_data *i;
@@ -341,7 +359,9 @@ char_data *get_char(char *name)
  * @param obj An object that will constrain the search to the location that
  * the object is in *if* the name argument is not a unique id.
  * @param name Character name keyword to search for, or unique ID. Unique
- * id must be prefixed with UID_CHAR. */
+ * id must be prefixed with UID_CHAR.
+ * @retval char_data * Pointer to the the char if found, NULL if not. Will
+ * only find god characters if DG_ALLOW_GODS is on. */
 char_data *get_char_near_obj(obj_data *obj, char *name)
 {
   char_data *ch;
@@ -369,11 +389,14 @@ char_data *get_char_near_obj(obj_data *obj, char *name)
  * @param room A room that will constrain the search to that location 
  * *if* the name argument is not a unique id.
  * @param name Character name keyword to search for, or unique ID. Unique
- * id must be prefixed with UID_CHAR. */
+ * id must be prefixed with UID_CHAR.
+ * @retval char_data * Pointer to the the char if found, NULL if not. Will
+ * only find god characters if DG_ALLOW_GODS is on. */
 char_data *get_char_in_room(room_data *room, char *name)
 {
   char_data *ch;
 
+
   if (*name == UID_CHAR) {
     ch = find_char(atoi(name + 1));
 
@@ -394,7 +417,8 @@ char_data *get_char_in_room(room_data *room, char *name)
  * @param obj The obj with which to constrain the search.
  * @param name The keyword of the object to search for. If 'self' or 'me'
  * are passed in as arguments, obj is returned. Can also be a unique object
- * id, and if so it must be prefixed with UID_CHAR. */
+ * id, and if so it must be prefixed with UID_CHAR.
+* @retval obj_data * Pointer to the object if found, NULL if not. */
 obj_data *get_obj_near_obj(obj_data *obj, char *name)
 {
   obj_data *i = NULL;