Documentation: streamline Source specs (#1648)

* Documentation: fixes #1497 and more

* work in progress

Author: martin-henz

docs/lib/array.js

@@ -1,17 +1,19 @@
 /**
- * returns
+ * **primitive**; returns
  * the current length of array <CODE>x</CODE>, which is 1 plus the
  * highest index that has been used so far in an array assignment on 
  * <CODE>x</CODE>. Here literal array expressions are counted too: The
  * array <CODE>[10, 20, 30]</CODE> has a length of 3.
+ * Time: <CODE>Θ(1)</CODE>, space: <CODE>Θ(1)</CODE>
  * @param {array} x - given array
  * @returns {number} current length of array
  */
 function array_length(x) {}
 
 /**
- * returns <CODE>true</CODE> if <CODE>x</CODE> 
+ * **primitive**; returns <CODE>true</CODE> if <CODE>x</CODE> 
  * is an array, and <CODE>false</CODE> if it is not.
+ * Time: <CODE>Θ(1)</CODE>, space: <CODE>Θ(1)</CODE>
  * @param {value} x - given value
  * @returns {boolean} whether <CODE>x</CODE> is an array
  */

docs/lib/list.js

@@ -1,70 +1,70 @@
 // \texttt{list.js START} \begin{lstlisting}
 
 /**
- * makes a pair whose head (first component) is <CODE>x</CODE>
- * and whose tail (second component) is <CODE>y</CODE>.
+ * **primitive**; makes a pair whose head (first component) is <CODE>x</CODE>
+ * and whose tail (second component) is <CODE>y</CODE>; time: <CODE>Θ(1)</CODE, space: <CODE>Θ(1)</CODE>.
  * @param {value} x - given head
  * @param {value} y - given tail
  * @returns {pair} pair with <CODE>x</CODE> as head and <CODE>y</CODE> as tail.
  */
 function pair(x, y) {}
 
 /**
- * returns <CODE>true</CODE> if <CODE>x</CODE> is a
- * pair and false otherwise.
+ *  **primitive**; returns <CODE>true</CODE> if <CODE>x</CODE> is a
+ * pair and false otherwise; time: <CODE>Θ(1)</CODE, space: <CODE>Θ(1)</CODE>.
  * @param {value} x - given value
  * @returns {boolean} whether <CODE>x</CODE> is a pair
  */
 function is_pair(x) {}
 
 /**
- * returns head (first component) of given pair <CODE>p</CODE>
+ *  **primitive**; returns head (first component) of given pair <CODE>p</CODE>; time: <CODE>Θ(1)</CODE, space: <CODE>Θ(1)</CODE>.
  * @param {pair} p - given pair
  * @returns {value} head of <CODE>p</CODE>
  */
 function head(p) {}
 
 /**
- * returns tail (second component of given pair <CODE>p</CODE>
+ *  **primitive**; returns tail (second component of given pair <CODE>p</CODE>; time: <CODE>Θ(1)</CODE, space: <CODE>Θ(1)</CODE>.
  * @param {pair} p - given pair
  * @returns {value} tail of <CODE>p</CODE>
  */
 function tail(p) {}
 
 /**
- * returns <CODE>true</CODE> if <CODE>x</CODE> is the
- * empty list <CODE>null</CODE>, and <CODE>false</CODE> otherwise.
+ *  **primitive**; returns <CODE>true</CODE> if <CODE>x</CODE> is the
+ * empty list <CODE>null</CODE>, and <CODE>false</CODE> otherwise; time: <CODE>Θ(1)</CODE, space: <CODE>Θ(1)</CODE>.
  * @param {value} x - given value
  * @returns {boolean} whether <CODE>x</CODE> is <CODE>null</CODE>
  */
 function is_null(x) {}
 
 /**
- * Returns <CODE>true</CODE> if
+ * **primitive**; returns <CODE>true</CODE> if
  * <CODE>xs</CODE> is a list as defined in the textbook, and
  * <CODE>false</CODE> otherwise. Iterative process; 
- * time: <CODE>O(n)</CODE>, space: <CODE>O(1)</CODE>, where <CODE>n</CODE>
+ * time: <CODE>Θ(n)</CODE>, space: <CODE>Θ(1)</CODE>, where <CODE>n</CODE>
  * is the length of the 
  * chain of <CODE>tail</CODE> operations that can be applied to <CODE>xs</CODE>.
- * recurses down the list and checks that it ends with the empty list null
+ * <CODE>is_list</CODE> recurses down the list and checks that it ends with the empty list null
  * @param {value} xs - given candidate
  * @returns whether {xs} is a list
  */
 function is_list(xs) {}
 
 /**
- * Given <CODE>n</CODE> values, returns a list of length <CODE>n</CODE>.
- * The elements of the list are the given values in the given order.
+ *  **primitive**; given <CODE>n</CODE> values, returns a list of length <CODE>n</CODE>.
+ * The elements of the list are the given values in the given order; time: <CODE>Θ(n)</CODE, space: <CODE>Θ(n)</CODE>.
  * @param {value} value1,value2,...,value_n - given values
  * @returns {list} list containing all values
  */
 function list(value1, value2, ...values ) {}
 
 /**
- * visualizes <CODE>x</CODE> in a separate drawing
- * area in the Source Academy using a box-and-pointer diagram; time, space:
- * O(n), where n is the total number of data structures such as
- * pairs in all the separate structures provided in <CODE>x</CODE>.
+ * visualizes the arguments in a separate drawing
+ * area in the Source Academy using box-and-pointer diagrams; time, space:
+ * <CODE>Θ(n)</CODE>, where <CODE>n</CODE> is the total number of data structures such as
+ * pairs in the arguments.
  * @param {value} value1,value2,...,value_n - given values
  * @returns {value} given <CODE>x</CODE>
  */
@@ -80,9 +80,10 @@ function list(value1, value2, ...values ) {}
  * need to be the same. If both are <CODE>undefined</CODE> or both are
  * <CODE>null</CODE>, the result is <CODE>true</CODE>. Otherwise they are compared
  * with <CODE>===</CODE> (using the definition of <CODE>===</CODE> in the
- * respective Source language in use). Time, space:
- * <CODE>O(n)</CODE>, where <CODE>n</CODE> is the number of pairs in
- * <CODE>x</CODE>.
+ * respective Source language in use).
+ * Time, space:
+ * <CODE>Θ(n)</CODE>, where <CODE>n</CODE> is the total number of data structures such as
+ * pairs in <CODE>x</CODE> and <CODE>y</CODE>.
  * @param {value} x - given value
  * @param {value} y - given value
  * @returns {boolean} whether <CODE>x</CODE> is structurally equal to <CODE>y</CODE>
@@ -109,8 +110,8 @@ function equal(xs, ys) {
 /**
  * Returns the length of the list
  * <CODE>xs</CODE>. 
- * Iterative process; time: <CODE>O(n)</CODE>, space:
- * <CODE>O(1)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE>, space:
+ * <CODE>Θ(1)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * @param {list} xs - given list
  * @returns {number} length of <CODE>xs</CODE>
  */
@@ -124,8 +125,8 @@ function $length(xs, acc) {
 /**
  * Returns a list that results from list
  * <CODE>xs</CODE> by element-wise application of unary function <CODE>f</CODE>. 
- * Iterative process; time: <CODE>O(n)</CODE>,
- * space: <CODE>O(n)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>),
+ * space: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>), where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * <CODE>f</CODE> is applied element-by-element:
  * <CODE>map(f, list(1, 2))</CODE> results in <CODE>list(f(1), f(2))</CODE>.
  * @param {function} f - unary 
@@ -146,7 +147,7 @@ function $map(f, xs, acc) {
  * Makes a list with <CODE>n</CODE>
  * elements by applying the unary function <CODE>f</CODE>
  * to the numbers 0 to <CODE>n - 1</CODE>, assumed to be a nonnegative integer.
- * Iterative process; time: <CODE>O(n)</CODE>, space: <CODE>O(n)</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>), space: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>).
  * @param {function} f - unary function
  * @param {number} n - given nonnegative integer
  * @returns {list} resulting list
@@ -161,8 +162,8 @@ function $build_list(i, fun, already_built) {
 /**
  * Applies unary function <CODE>f</CODE> to every
  * element of the list <CODE>xs</CODE>.
- * Iterative process; time: <CODE>O(n)</CODE>, space: <CODE>O(1)</CODE>,
- * Where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>), space: <CODE>Θ(1)</CODE> (apart from <CODE>f</CODE>),
+ * where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * <CODE>f</CODE> is applied element-by-element:
  * <CODE>for_each(fun, list(1, 2))</CODE> results in the calls
  * <CODE>fun(1)</CODE> and <CODE>fun(2)</CODE>.
@@ -185,6 +186,9 @@ function for_each(fun, xs) {
  * Returns a string that represents
  * list <CODE>xs</CODE> using the text-based box-and-pointer notation
  * <CODE>[...]</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE> where <CODE>n</CODE> is the size of the list, space: <CODE>Θ(m)</CODE> where <CODE>m</CODE> is the length of the string.
+ * The process is iterative, but consumes space <CODE>O(m)</CODE>
+ * because of the result string.
  * @param {list} xs - given list
  * @returns {string} <CODE>xs</CODE> converted to string
  */
@@ -205,9 +209,9 @@ function $list_to_string(xs, cont) {
 
 /**
  * Returns list <CODE>xs</CODE> in reverse
- * order. Iterative process; time: <CODE>O(n)</CODE>,
- * space: <CODE>O(n)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
- * The process is iterative, but consumes space <CODE>O(n)</CODE>
+ * order. Iterative process; time: <CODE>Θ(n)</CODE>,
+ * space: <CODE>Θ(n)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * The process is iterative, but consumes space <CODE>Θ(n)</CODE>
  * because of the result list.
  * @param {list} xs - given list
  * @returns {list} <CODE>xs</CODE> in reverse
@@ -224,8 +228,8 @@ function $reverse(original, reversed) {
 /**
  * Returns a list that results from 
  * appending the list <CODE>ys</CODE> to the list <CODE>xs</CODE>.
- * Iterative process; time: <CODE>O(n)</CODE>, space:
- * <CODE>O(n)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE>, space:
+ * <CODE>Θ(n)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * In the result, null at the end of the first argument list
  * is replaced by the second argument, regardless what the second
  * argument consists of.
@@ -247,8 +251,8 @@ function $append(xs, ys, cont) {
  * whose head is identical to
  * <CODE>v</CODE> (using <CODE>===</CODE>); returns <CODE>null</CODE> if the
  * element does not occur in the list.
- * Iterative process; time: <CODE>O(n)</CODE>,
- * space: <CODE>O(1)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process; time: <CODE>Θ(n)</CODE>,
+ * space: <CODE>Θ(1)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * @param {value} v - given value
  * @param {list} xs - given list
  * @returns {list} postfix sublist that starts with <CODE>v</CODE>
@@ -266,7 +270,7 @@ function member(v, xs) {
  * is identical (<CODE>===</CODE>) to <CODE>v</CODE>.
  * Returns the original
  * list if there is no occurrence. Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(n)</CODE>, where <CODE>n</CODE>
+ * time: <CODE>Θ(n)</CODE>, space: <CODE>Θ(n)</CODE>, where <CODE>n</CODE>
  * is the length of <CODE>xs</CODE>.
  * @param {value} v - given value
  * @param {list} xs - given list
@@ -290,7 +294,7 @@ function $remove(v, xs, acc) {
  * Returns the original
  * list if there is no occurrence.  
  * Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(n)</CODE>, where <CODE>n</CODE>
+ * time: <CODE>Θ(n)</CODE>, space: <CODE>Θ(n)</CODE>, where <CODE>n</CODE>
  * is the length of <CODE>xs</CODE>.
  * @param {value} v - given value
  * @param {list} xs - given list
@@ -313,7 +317,7 @@ function $remove_all(v, xs, acc) {
  * <CODE>pred</CODE>
  * returns <CODE>true</CODE>.
  * Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(n)</CODE>,
+ * time: <CODE>Θ(n)</CODE> (apart from <CODE>pred</CODE>), space: <CODE>Θ(n)</CODE> (apart from <CODE>pred</CODE>),
  * where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * @param {function} pred - unary function returning boolean value
  * @param {list} xs - given list
@@ -335,7 +339,7 @@ function $filter(pred, xs, acc) {
  * numbers starting from <CODE>start</CODE> using a step size of 1, until
  * the number exceeds (<CODE>&gt;</CODE>) <CODE>end</CODE>.
  * Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(n)</CODE>,
+ * time: <CODE>Θ(n)</CODE>, space: <CODE>Θ(n)</CODE>,
  * where <CODE>n</CODE> is <CODE>end - start</CODE>.
  * @param {number} start - starting number
  * @param {number} end - ending number
@@ -355,7 +359,7 @@ function $enum_list(start, end, acc) {
  * of list <CODE>xs</CODE> at position <CODE>n</CODE>, 
  * where the first element has index 0.
  * Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(1)</CODE>,
+ * time: <CODE>Θ(n)</CODE>, space: <CODE>Θ(1)</CODE>,
  * where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * @param {list} xs - given list
  * @param {number} n - given position
@@ -380,9 +384,8 @@ function list_ref(xs, n) {
  * list. Thus, <CODE>accumulate(f,zero,list(1,2,3))</CODE> results in
  * <CODE>f(1, f(2, f(3, zero)))</CODE>.
  * Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(n)</CODE>,
- * where <CODE>n</CODE> is the length of <CODE>xs</CODE>
- * assuming <CODE>f</CODE> takes constant time.
+ * time: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>), space: <CODE>Θ(n)</CODE> (apart from <CODE>f</CODE>),
+ * where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
  * @param {function} f - binary function
  * @param {value} initial - initial value
  * @param {list} xs - given list
@@ -399,8 +402,11 @@ function $accumulate(f, initial, xs, cont) {
 
 
 /**
- *  Optional second argument.
- *  Similar to <CODE>display</CODE>, but formats well-formed lists nicely if detected.
+ * Optional second argument.
+ * Similar to <CODE>display</CODE>, but formats well-formed lists nicely if detected;
+ * time, space:
+ * <CODE>Θ(n)</CODE>, where <CODE>n</CODE> is the total number of data structures such as
+ * pairs in <CODE>x</CODE>.
  * @param {value} xs - list structure to be displayed
  * @param {string} s to be displayed, preceding <CODE>xs</CODE>
  * @returns {value} xs, the first argument value

docs/lib/stream.js

@@ -35,11 +35,8 @@ function stream_tail(xs) {
 /**
  * Returns <CODE>true</CODE> if
  * <CODE>xs</CODE> is a stream as defined in the textbook, and
- * <CODE>false</CODE> otherwise. Iterative process; 
- * time: <CODE>O(n)</CODE>, space: <CODE>O(1)</CODE>, where <CODE>n</CODE>
- * is the length of the 
- * chain of <CODE>stream_tail</CODE> operations that can be applied to <CODE>xs</CODE>.
- * recurses down the stream and checks that it ends with the empty stream null.
+ * <CODE>false</CODE> otherwise. Iterative process.
+ * Recurses down the stream and checks that it ends with the empty stream null.
  * Laziness:  No: <CODE>is_stream</CODE> needs to force the given stream.
  * @param {value} xs - given candidate
  * @returns {boolean} whether <CODE>xs</CODE> is a stream
@@ -107,8 +104,7 @@ function stream() {
 /**
  * Returns the length of the stream
  * <CODE>xs</CODE>. 
- * Iterative process; time: <CODE>O(n)</CODE>, space:
- * <CODE>O(1)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process.
  * Lazy? No: The function needs to explore the whole stream 
  * @param {stream} xs - given stream
  * @returns {number} length of <CODE>xs</CODE>
@@ -165,8 +161,7 @@ function build_stream(fun, n) {
 /**
  * Applies unary function <CODE>f</CODE> to every
  * element of the stream <CODE>xs</CODE>.
- * Iterative process; time: <CODE>O(n)</CODE>, space: <CODE>O(1)</CODE>,
- * Where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process.
  * <CODE>f</CODE> is applied element-by-element:
  * <CODE>stream_for_each(f, stream(1, 2))</CODE> results in the calls
  * <CODE>f(1)</CODE> and <CODE>f(2)</CODE>.
@@ -188,9 +183,8 @@ function stream_for_each(fun, xs) {
 
 /**
  * Returns stream <CODE>xs</CODE> in reverse
- * order. Iterative process; time: <CODE>O(n)</CODE>,
- * space: <CODE>O(n)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
- * The process is iterative, but consumes space <CODE>O(n)</CODE>
+ * order. Iterative process.
+ * The process is iterative, but consumes space <CODE>Ω(n)</CODE>
  * because of the result stream.
  * Lazy? No: <CODE>stream_reverse</CODE> 
  * forces the exploration of the entire stream
@@ -232,8 +226,7 @@ function stream_append(xs, ys) {
  * whose head is identical to
  * <CODE>v</CODE> (using <CODE>===</CODE>); returns <CODE>null</CODE> if the
  * element does not occur in the stream.
- * Iterative process; time: <CODE>O(n)</CODE>,
- * space: <CODE>O(1)</CODE>, where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process.
  * Lazy? Sort-of: <CODE>stream_member</CODE> 
  * forces the stream only until the element 
  * is found.
@@ -375,9 +368,7 @@ function eval_stream(s, n) {
  * Returns the element
  * of stream <CODE>xs</CODE> at position <CODE>n</CODE>, 
  * where the first element has index 0.
- * Iterative process;
- * time: <CODE>O(n)</CODE>, space: <CODE>O(1)</CODE>,
- * where <CODE>n</CODE> is the length of <CODE>xs</CODE>.
+ * Iterative process.
  * Lazy? Sort-of: <CODE>stream_ref</CODE> only forces the computation of
  *                the first <CODE>n</CODE> elements, and leaves the rest of
  *                the stream untouched.

docs/specs/source_1.tex

@@ -29,13 +29,10 @@
 
 \input source_typing
 
-\section{Standard Libraries}
+\input source_standard
 
-The following libraries are always available in this language.
-
-\input source_misc
-
-\input source_math
+The standard library for Source \S\ 1 is documented in
+\href{}{online documentation of Source \S\ 1}.
 
 \input source_js_differences
 

docs/specs/source_1_lazy.tex

@@ -54,9 +54,7 @@ \section{Changes}
 
 \input source_typing
 
-\section{Standard Libraries}
-
-The following libraries are always available in this language.
+\input source_standard
 
 \input source_misc
 

docs/specs/source_1_typed.tex

@@ -33,9 +33,7 @@
 
 \input source_typing
 
-\section{Standard Libraries}
-
-The following libraries are always available in this language.
+\input source_standard
 
 \input source_misc
 

docs/specs/source_2.tex

@@ -37,9 +37,7 @@ \section{Changes}
 
 \input source_typing
 
-\section{Standard Libraries}
-
-The following libraries are always available in this language.
+\input source_standard
 
 \input source_misc