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

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

diff --git a/libguile/variable.c b/libguile/variable.c
index 16aa29f..f74a58d 100644 (file)
--- 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);

diff --git a/libguile/version.c b/libguile/version.c
index 11ba79f..17292bf 100644 (file)
--- a/libguile/version.c
+++ b/libguile/version.c
@@ -53,8 +53,9 @@
 /* Return a Scheme string containing Guile's major version number.  */
 
 SCM_DEFINE (scm_major_version, "major-version", 0, 0, 0, 
-           (),
-"")
+            (),
+            "Return a string containing Guile's major version number.\n"
+            "E.g., \"1\".")
 #define FUNC_NAME s_scm_major_version
 {
   return scm_makfrom0str (GUILE_MAJOR_VERSION);
@@ -64,8 +65,9 @@ SCM_DEFINE (scm_major_version, "major-version", 0, 0, 0,
 /* Return a Scheme string containing Guile's minor version number.  */
 
 SCM_DEFINE (scm_minor_version, "minor-version", 0, 0, 0, 
-           (),
-"")
+            (),
+            "Return a string containing Guile's minor version number.\n"
+            "E.g., \"3.5\".")
 #define FUNC_NAME s_scm_minor_version
 {
   return scm_makfrom0str (GUILE_MINOR_VERSION);
@@ -75,7 +77,7 @@ SCM_DEFINE (scm_minor_version, "minor-version", 0, 0, 0,
 /* Return a Scheme string containing Guile's complete version.  */
 
 SCM_DEFINE (scm_version, "version", 0, 0, 0, 
-           (),
+            (),
            "@deffnx primitive major-version\n"
            "@deffnx primitive minor-version\n"
            "Return a string describing Guile's version number, or its major or minor\n"