docs: more documentation work

core/Double.carp

@@ -46,6 +46,7 @@
         min
         val)))
 
+  (doc approx "checks whether x and y are approximately (i.e. margin of error of 0.00001) equal")
   (defn approx [x y]
     (if (> x y)
       (< (- x y) 0.00001)

core/Filepath.carp

@@ -2,8 +2,10 @@
 
   (use Array)
 
+  (private append-slash)
+  (hidden append-slash)
   (defn append-slash [s]
-  (str* s "/"))
+    (str* s "/"))
 
   (doc dir-from-path "Removes the file-name part of a path to a file.")
   (defn dir-from-path [path]

core/Float.carp

@@ -24,6 +24,7 @@
         min
         val)))
 
+  (doc approx "checks whether x and y are approximately (i.e. margin of error of 0.00001) equal")
   (defn approx [x y]
     (if (> x y)
       (< (- x y) 0.00001f)

core/Format.carp

@@ -1,3 +1,5 @@
+(private fmt-internal)
+(hidden fmt-internal)
 (defdynamic fmt-internal [s args]
   (let [idx (String.index-of s \%)
         len (String.count s)]
@@ -21,5 +23,6 @@
                                      (fmt-internal (String.substring s (+ (inc idx) next) len)
                                                    (cdr args)))))))))))
 
+(doc fmt "fmt formats a string. It supports all of the string interpolations defined in format of the type that should be interpolated (e.g. %d and %x on integers).")
 (defmacro fmt [s :rest args]
   (fmt-internal s args))

core/Geometry.carp

@@ -1,7 +1,9 @@
 (defmodule Geometry
+  (doc degree-to-radians "Converts degrees expressed as a double into radians.")
   (defn degree-to-radians [n]
     (Double.* n (Double./ Double.pi 180.0)))
 
+  (doc radians-to-degree "Converts radians expressed as a double into degree.")
   (defn radians-to-degree [n]
     (Double.* n (Double./ 180.0 Double.pi)))
 )

core/IO.carp

@@ -3,18 +3,30 @@
 (register-type FILE)
 
 (defmodule IO
+  (doc println "prints a string ref to stdout, appends a newline.")
   (register println (Fn [(Ref String)] ()))
+  (doc print "prints a string ref to stdout, does not append a newline.")
   (register print (Fn [(Ref String)] ()))
+  (doc get-line "gets a line from stdin.")
   (register get-line (Fn [] String))
+  (doc get-char "gets a character from stdin.")
   (register get-char (Fn [] Char) "getchar")
+  (doc read-file "returns the contents of a file passed as argument as a string.")
   (register read-file (Fn [&String] String))
+  (doc exit "exit the current program with a return code.")
   (register exit (Fn [Int] a))
   (register EOF Char)
+  (doc EOF "the End-Of-File character as a literal.")
+  (doc fopen "opens a file by name using a mode (one or multiple of [r]ead, [w]rite, and [a]ppend), returns a file pointer.")
   (register fopen (Fn [&String &String] (Ptr FILE)))
+  (doc fclose "closes a file pointer.")
   (register fclose (Fn [(Ptr FILE)] ()))
+  (doc fgetc "gets a character from a file pointer.")
   (register fgetc (Fn [(Ptr FILE)] Char))
+  (doc fwrite "writes to a file pointer.")
   (register fwrite (Fn [a Int Int (Ptr FILE)] ()) "fwrite")
 
+  (doc read->EOF "reads a file given by name until the End-Of-File character is reached.")
   (defn read->EOF [filename]
     (let [f (IO.fopen filename "rb")
           c (Char.from-int 0)