* variable.c, version.c: Added documentation, written by hand

since I could not find anything already written that was
relevant.

1 files changed, 34 insertions, 14 deletions

diff --git a/libguile/variable.c b/libguile/variable.c
index 16aa29f5b..f74a58d85 100644
--- a/libguile/variable.c
+++ b/libguile/variable.c
@@ -100,8 +100,13 @@ make_vcell_variable (SCM vcell)
 }
 
 SCM_DEFINE (scm_make_variable, "make-variable", 1, 1, 0, 
-           (SCM init, SCM name_hint),
-"")
+            (SCM init, SCM name_hint),
+            "Return a variable object initialized to value INIT.\n"
+            "If given, uses NAME-HINT as its internal (debugging)\n"
+            "name, otherwise just treat it as an anonymous variable.\n"
+            "Remember, of course, that multiple bindings to the same\n"
+            "variable may exist, so NAME-HINT is just that---a hint.\n"
+            "")
 #define FUNC_NAME s_scm_make_variable
 {
   SCM val_cell;
@@ -120,8 +125,13 @@ SCM_DEFINE (scm_make_variable, "make-variable", 1, 1, 0,
 
 
 SCM_DEFINE (scm_make_undefined_variable, "make-undefined-variable", 0, 1, 0, 
-           (SCM name_hint),
-"")
+            (SCM name_hint),
+            "Return a variable object initialized to an undefined value.\n"
+            "If given, uses NAME-HINT as its internal (debugging)\n"
+            "name, otherwise just treat it as an anonymous variable.\n"
+            "Remember, of course, that multiple bindings to the same\n"
+            "variable may exist, so NAME-HINT is just that---a hint.\n"
+            "")
 #define FUNC_NAME s_scm_make_undefined_variable
 {
   SCM vcell;
@@ -140,8 +150,8 @@ SCM_DEFINE (scm_make_undefined_variable, "make-undefined-variable", 0, 1, 0,
 
 
 SCM_DEFINE (scm_variable_p, "variable?", 1, 0, 0, 
-           (SCM obj),
-"")
+            (SCM obj),
+            "Return #t iff OBJ is a variable object, else return #f\n")
 #define FUNC_NAME s_scm_variable_p
 {
   return SCM_BOOL(SCM_VARIABLEP (obj));
@@ -150,8 +160,10 @@ SCM_DEFINE (scm_variable_p, "variable?", 1, 0, 0,
 
 
 SCM_DEFINE (scm_variable_ref, "variable-ref", 1, 0, 0, 
-           (SCM var),
-"")
+            (SCM var),
+            "Dereference VAR and return its value.\n"
+            "VAR must be a variable object;  see `make-variable' and\n"
+            "`make-undefined-variable'")
 #define FUNC_NAME s_scm_variable_ref
 {
   SCM_VALIDATE_VARIABLE (1,var);
@@ -162,8 +174,11 @@ SCM_DEFINE (scm_variable_ref, "variable-ref", 1, 0, 0,
 
 
 SCM_DEFINE (scm_variable_set_x, "variable-set!", 2, 0, 0,
-           (SCM var, SCM val),
-"")
+            (SCM var, SCM val),
+            "Set the value of the variable VAR to VAL.\n"
+            "VAR must be a variable object, VAL can be any value.\n"
+            "Returns an unspecified value.\n"
+            "")
 #define FUNC_NAME s_scm_variable_set_x
 {
   SCM_VALIDATE_VARIABLE (1,var);
@@ -174,8 +189,11 @@ SCM_DEFINE (scm_variable_set_x, "variable-set!", 2, 0, 0,
 
 
 SCM_DEFINE (scm_builtin_variable, "builtin-variable", 1, 0, 0, 
-           (SCM name),
-"")
+            (SCM name),
+            "Return the built-in variable with the name NAME.\n"
+            "NAME must be a symbol (not a string).\n"
+            "Then use `variable-ref' to access its value.\n"
+            "")
 #define FUNC_NAME s_scm_builtin_variable
 {
   SCM vcell;
@@ -201,8 +219,10 @@ SCM_DEFINE (scm_builtin_variable, "builtin-variable", 1, 0, 0,
 
 
 SCM_DEFINE (scm_variable_bound_p, "variable-bound?", 1, 0, 0, 
-           (SCM var),
-"")
+            (SCM var),
+            "Return #t iff VAR is bound to a value.\n"
+            "Throws an error if VAR is not a variable object.\n"
+            "")
 #define FUNC_NAME s_scm_variable_bound_p
 {
   SCM_VALIDATE_VARIABLE (1,var);