From 67a0a3ba608c9ba3d6bb7e8c78339377018fbe26 Mon Sep 17 00:00:00 2001
From: "H. William Welliver III" <bill@welliver.org>
Date: Mon, 12 Sep 2005 03:45:47 -0400
Subject: [PATCH] some more doxygenification
Rev: src/array.c:1.182
Rev: src/array.h:1.68
Rev: src/svalue.h:1.136
---
src/array.c | 64 ++++++++++++++++++++++++++++++++++++++++++++++------
src/array.h | 9 ++++----
src/svalue.h | 46 +++++++++++++++++++++----------------
3 files changed, 87 insertions(+), 32 deletions(-)
diff --git a/src/array.c b/src/array.c
index 89054bd819..d6bfad7773 100644
--- a/src/array.c
+++ b/src/array.c
@@ -2,7 +2,7 @@
|| This file is part of Pike. For copyright information see COPYRIGHT.
|| Pike is distributed under GPL, LGPL and MPL. See the file COPYING
|| for more information.
-|| $Id: array.c,v 1.181 2005/05/19 22:35:23 mast Exp $
+|| $Id: array.c,v 1.182 2005/09/12 07:45:47 bill Exp $
*/
#include "global.h"
@@ -228,7 +228,7 @@ PMOD_EXPORT void array_index(struct svalue *s,struct array *v,INT32 index)
free_array(v);
}
-/* Is destructive on data if destructive is set and it only has one ref. */
+/** Is destructive on data if destructive is set and it only has one ref. */
PMOD_EXPORT struct array *array_column (struct array *data, struct svalue *index,
int destructive)
{
@@ -334,7 +334,12 @@ PMOD_EXPORT void array_free_index(struct array *v,INT32 index)
free_svalue(ITEM(v) + index);
}
-
+/** set an element in an array to a value.
+ *
+ * @param a the array whose element is to be set
+ * @param ind an int or string containing the index to set
+ * @param s the value to set
+ */
PMOD_EXPORT void simple_set_index(struct array *a,struct svalue *ind,struct svalue *s)
{
switch (ind->type) {
@@ -550,6 +555,9 @@ PMOD_EXPORT struct array *array_remove(struct array *v,INT32 index)
/**
* Search for in svalue in an array.
+ * @param v the array to search
+ * @param s the value to search for
+ * @param start the index to start search at
* @return the index if found, -1 otherwise
*/
PMOD_EXPORT ptrdiff_t array_search(struct array *v, struct svalue *s,
@@ -594,6 +602,9 @@ PMOD_EXPORT ptrdiff_t array_search(struct array *v, struct svalue *s,
/**
* Slice a piece of an array (nondestructively)
+ * @param v the array to slice
+ * @param start the beginning element to be included
+ * @param end the element beyond the end of the slice
* @return an array consisting of v[start..end-1]
*/
PMOD_EXPORT struct array *slice_array(struct array *v, ptrdiff_t start,
@@ -667,6 +678,8 @@ PMOD_EXPORT struct array *friendly_slice_array(struct array *v,
/**
* Copy an array.
+ * @param v the array to be copied.
+ * @returns the copy of the input array.
*/
PMOD_EXPORT struct array *copy_array(struct array *v)
{
@@ -1441,6 +1454,11 @@ PMOD_EXPORT struct array *array_zip(struct array *a, struct array *b,INT32 *zipp
return ret;
}
+/** add an arbitrary number of arrays together
+* @param argp an array of svalues containing the arrays to be concatenated
+* @param args the number of elements in argp
+* @returns the resulting struct array.
+*/
PMOD_EXPORT struct array *add_arrays(struct svalue *argp, INT32 args)
{
INT32 e, size;
@@ -1770,7 +1788,7 @@ PMOD_EXPORT struct array *merge_array_without_order2(struct array *a, struct arr
}
-/* merge two arrays without paying attention to the order
+/** merge two arrays without paying attention to the order
* the elements has presently
*/
PMOD_EXPORT struct array *merge_array_without_order(struct array *a,
@@ -1811,8 +1829,8 @@ PMOD_EXPORT struct array *merge_array_without_order(struct array *a,
#endif
}
-/* subtract an array from another */
-
+/** subtract an array from another
+*/
PMOD_EXPORT struct array *subtract_arrays(struct array *a, struct array *b)
{
#ifdef PIKE_DEBUG
@@ -1837,7 +1855,9 @@ PMOD_EXPORT struct array *subtract_arrays(struct array *a, struct array *b)
}
}
-/* and two arrays */
+/**
+ * and two arrays
+ */
PMOD_EXPORT struct array *and_arrays(struct array *a, struct array *b)
{
#ifdef PIKE_DEBUG
@@ -1938,6 +1958,9 @@ node *make_node_from_array(struct array *a)
}
}
+/**
+* push elements of an array onto the stack.
+*/
PMOD_EXPORT void push_array_items(struct array *a)
{
check_stack(a->size);
@@ -2049,6 +2072,11 @@ PMOD_EXPORT struct array *aggregate_array(INT32 args)
return a;
}
+/** add an element to the end of an array by resizing the array.
+ *
+ * @param a the array to be appended
+ * @param s the value to be added to the new element in the array
+ */
PMOD_EXPORT struct array *append_array(struct array *a, struct svalue *s)
{
a=resize_array(a,a->size+1);
@@ -2058,6 +2086,12 @@ PMOD_EXPORT struct array *append_array(struct array *a, struct svalue *s)
typedef char *(* explode_searchfunc)(void *,void *,size_t);
+/** explode a string by a delimiter
+ *
+ * @param str the string to be split
+ * @param del the string to split str by
+ * @returns an array containing the elements of the split string
+ */
PMOD_EXPORT struct array *explode(struct pike_string *str,
struct pike_string *del)
{
@@ -2145,6 +2179,14 @@ PMOD_EXPORT struct array *explode(struct pike_string *str,
return ret;
}
+/** implode an array by creating a string with all of the array's elements
+ * separated by a delimiter
+ *
+ * @param a the array containing elements to be imploded
+ * @param del the delimiter used to separate the array's elements in the resulting string
+ * @returns the imploded string
+ *
+ */
PMOD_EXPORT struct pike_string *implode(struct array *a,struct pike_string *del)
{
INT32 len,e, inited;
@@ -2188,6 +2230,8 @@ PMOD_EXPORT struct pike_string *implode(struct array *a,struct pike_string *del)
return low_end_shared_string(ret);
}
+/** deeply copy an array
+ */
PMOD_EXPORT struct array *copy_array_recursively(struct array *a,
struct mapping *m)
{
@@ -2221,6 +2265,8 @@ PMOD_EXPORT struct array *copy_array_recursively(struct array *a,
return ret;
}
+/** apply the elements of an array
+ */
PMOD_EXPORT void apply_array(struct array *a, INT32 args)
{
INT32 e;
@@ -2258,6 +2304,10 @@ PMOD_EXPORT void apply_array(struct array *a, INT32 args)
stack_pop_n_elems_keep_top(args);
}
+/** reverse the elements in an array
+ * if the array has more than one reference, the array will be reversed
+ * into a new array. otherwise, the same array is reversed.
+ */
PMOD_EXPORT struct array *reverse_array(struct array *a)
{
INT32 e;
diff --git a/src/array.h b/src/array.h
index 3e991973ed..995beb5499 100644
--- a/src/array.h
+++ b/src/array.h
@@ -2,7 +2,7 @@
|| This file is part of Pike. For copyright information see COPYRIGHT.
|| Pike is distributed under GPL, LGPL and MPL. See the file COPYING
|| for more information.
-|| $Id: array.h,v 1.67 2004/10/18 00:42:36 bill Exp $
+|| $Id: array.h,v 1.68 2005/09/12 07:45:47 bill Exp $
*/
#ifndef ARRAY_H
@@ -214,7 +214,7 @@ PMOD_EXPORT struct array *implode_array(struct array *a, struct array *b);
gc_cycle_enqueue((gc_cycle_check_cb *) real_gc_cycle_check_array, (X), (WEAK))
-/* Macros for aggregating results built on the stack into an array,
+/** Macros for aggregating results built on the stack into an array,
* while maintaining a bound on stack consumption. Use like this:
*
* check_stack(120);
@@ -228,7 +228,6 @@ PMOD_EXPORT struct array *implode_array(struct array *a, struct array *b);
*
* The array is left on top of the stack.
*/
-
#define BEGIN_AGGREGATE_ARRAY(estimated_size) do { \
struct svalue *base__; \
push_array(allocate_array_no_init(0, (estimated_size))); \
@@ -261,7 +260,7 @@ PMOD_EXPORT struct array *implode_array(struct array *a, struct array *b);
} while (0)
-/*
+/**
* Extract an svalue from an array
*/
#define array_index_no_free(S,A,I) do { \
@@ -276,7 +275,7 @@ PMOD_EXPORT struct array *implode_array(struct array *a, struct array *b);
}while(0)
-/*
+/**
* Sets an index in an array.
*
* @param V the array to modify
diff --git a/src/svalue.h b/src/svalue.h
index 3cfb2b4fa1..c913545025 100644
--- a/src/svalue.h
+++ b/src/svalue.h
@@ -2,7 +2,7 @@
|| This file is part of Pike. For copyright information see COPYRIGHT.
|| Pike is distributed under GPL, LGPL and MPL. See the file COPYING
|| for more information.
-|| $Id: svalue.h,v 1.135 2005/09/06 16:56:17 grubba Exp $
+|| $Id: svalue.h,v 1.136 2005/09/12 07:45:47 bill Exp $
*/
#ifndef SVALUE_H
@@ -59,9 +59,11 @@ struct processing
struct ref_dummy;
+/** the union of possible types in an svalue.
+*/
union anything
{
- INT_TYPE integer; /* Union initializations assume this first. */
+ INT_TYPE integer; /**< Union initializations assume this first. */
struct callable *efun;
struct array *array;
struct mapping *mapping;
@@ -73,8 +75,8 @@ union anything
INT32 *refs;
struct ref_dummy *dummy;
FLOAT_TYPE float_number;
- int identifier; /* Used with T_OBJ_INDEX. */
- struct svalue *lval; /* Used with T_SVALUE_PTR. */
+ int identifier; /**< Used with T_OBJ_INDEX. */
+ struct svalue *lval; /**< Used with T_SVALUE_PTR. */
void *ptr;
};
@@ -85,11 +87,13 @@ union anything
/* Note: At least multisets overlays the type field and uses the top 4
* bits in it internally. */
+/**
+ */
struct svalue
{
- unsigned INT16 type;
- unsigned INT16 subtype;
- union anything u;
+ unsigned INT16 type; /**< the data type, see PIKE_T_... */
+ unsigned INT16 subtype; /**< used to store the zero type, among others */
+ union anything u; /**< contains the value */
};
#define PIKE_T_ARRAY 0
@@ -103,30 +107,32 @@ struct svalue
#define PIKE_T_INT 8
#define PIKE_T_FLOAT 9
-#define PIKE_T_ZERO 14 /* Can return 0, but nothing else */
+#define PIKE_T_ZERO 14 /**< Can return 0, but nothing else */
+
+
#define T_UNFINISHED 15
-#define T_VOID 16
-/* Can't return any value. Also used on stack to fill out the second
+#define T_VOID 16 /**< Can't return any value. Also used on stack to fill out the second
* svalue on an lvalue when it isn't used. */
+
#define T_MANY 17
#define PIKE_T_RING 240
-#define PIKE_T_NAME 241 /* Named type. */
-#define PIKE_T_SCOPE 243 /* Not supported yet */
-#define PIKE_T_TUPLE 244 /* Not supported yet */
+#define PIKE_T_NAME 241 /**< Named type. */
+#define PIKE_T_SCOPE 243 /**< Not supported yet */
+#define PIKE_T_TUPLE 244 /**< Not supported yet */
#define T_ASSIGN 245
#define T_DELETED 246
#define PIKE_T_UNKNOWN 247
-#define T_OBJ_INDEX 248
-/* svalue.u.identifer is an identifier index in an object. Primarily
+/** svalue.u.identifer is an identifier index in an object. Primarily
* used in lvalues on stack. */
+#define T_OBJ_INDEX 248
-#define T_SVALUE_PTR 249
-/* svalue.u.lval points to an svalue. Primarily used in lvalues on
+/** svalue.u.lval points to an svalue. Primarily used in lvalues on
* stack. */
+#define T_SVALUE_PTR 249
#define T_ARRAY_LVALUE 250
#define PIKE_T_MIXED 251
@@ -236,16 +242,16 @@ struct svalue
#define BIT_ZERO (1<<PIKE_T_ZERO)
-/* Used to signify that the type field hasn't been set according to
+/** Used to signify that the type field hasn't been set according to
* reality. */
#define BIT_UNFINISHED (1 << T_UNFINISHED)
-/* This is only used in typechecking to signify that this
+/** This is only used in typechecking to signify that this
* argument may be omitted.
*/
#define BIT_VOID (1 << T_VOID)
-/* This is used in typechecking to signify that the rest of the
+/** This is used in typechecking to signify that the rest of the
* arguments has to be of this type.
*/
#define BIT_MANY (1 << T_MANY)
--
GitLab