Update README.rst (#293)

* Update README.rst

* Update README.rst

Co-Authored-By: Christian James Welly <[email protected]>

* missing js files as sources for jsdoc

* Update README.rst

Co-Authored-By: Christian James Welly <[email protected]>

* Update README.rst

Co-Authored-By: Christian James Welly <[email protected]>

Author: martin-henz

README.rst

@@ -20,7 +20,7 @@ To build,
 .. code-block::
 
   $ git clone https://github.com/source-academy/js-slang.git
-  $ cd slang
+  $ cd js-slang
   $ yarn
   $ yarn build
 
@@ -37,6 +37,20 @@ or alternatively, install js-slang and run
   $ npm -g install js-slang   # Install js-slang
   $ js-slang [chapter] # default: 1
 
+Documentation
+-------------
+
+Source is documented here: https://sicp.comp.nus.edu.sg/source/
+
+To build the documentation, run
+
+.. code-block::
+
+  $ git clone https://github.com/source-academy/js-slang.git
+  $ cd js-slang
+  $ npm install # If additional permissions are required, run sudo npm install
+  $ make           # to make the PDF documents using LaTeX
+  $ yarn run jsdoc # to make the web pages in js-slang/doc/source
 
 Error messages
 --------------

doc/array.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ * @param {array} x - given array
+ * @returns {number} current length of array
+ */
+function array_length(x) {}
+
+/**
+ * returns <CODE>true</CODE> if <CODE>x</CODE> 
+ * is an array, and <CODE>false</CODE> if it is not.
+ * @param {value} x - given value
+ * @returns {boolean} whether <CODE>x</CODE> is an array
+ */
+function is_array(x) {}
+

doc/mce.js

@@ -0,0 +1,24 @@
+/**
+ * returns the parse tree that results from parsing
+ * the string `str` as a Source program. The format
+ * of the parse tree is described in chapter 4 of 
+ * the textbook 
+ * in <a href="https://sicp.comp.nus.edu.sg/">Structure and
+ * Interpretation of Computer Programs, JavaScript Adaptation</a> (SICP).
+ * @param {string} x - given program as a string
+ * @returns {value} parse tree
+ */
+function parse(str) {}
+
+/**
+ * calls the function `f`
+ * with arguments given in list `xs`. For example: <PRE><CODE>function times(x, y) {
+ * return x * y;
+ * }
+ * apply_in_underlying_javascript(times, list(2, 3)); // returns 6</CODE></PRE>
+ * @param {function} f - function to be applied
+ * @param {list} xs - arguments given in list
+ * @returns {boolean} whatever `f` returns
+ */
+function apply_in_underlying_javascript(f, xs) {}
+

doc/pairmutator.js

@@ -0,0 +1,15 @@
+/**
+ * changes the pair <CODE>p</CODE> such that its head is <CODE>x</CODE>.
+ * @param {pair} p - given pair
+ * @param {value} x - given value
+ * @returns {undefined} undefined
+ */
+function set_head(p, x) {}
+
+/**
+ * changes the pair <CODE>p</CODE> such that its tail is <CODE>x</CODE>.
+ * @param {pair} p - given pair
+ * @param {value} x - given value
+ * @returns {undefined} undefined
+ */
+function set_tail(p, x) {}