Skip to content

Commit 0cc01dc

Browse files
martin-henzmartin-henz
authored
Library documentation (#271)
* starting documentation project * setting things up for documentation project * getting closer to a complete setup * work in progress * more reader-friendly * missing js added * another missing js added * small changes in the READMEs; bug in jsdoc.sh in ALL * added links and simplified text * attempt to complete the lib docs * christians comments * fixes item 6 in #294 * Christians comments * fixing tags in header
1 parent 94838ba commit 0cc01dc

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+15174
-112
lines changed

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,7 @@ node_modules
22
*.js
33
*.map
44
dist/
5+
6+
# emacs backup files
7+
8+
*~

‎README.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,25 @@ including specifics and correction guides, should be left to elaborate().
5353

5454
Please remember to write test cases to reflect your added functionalities. The god of this repository is self-professed
5555
to be very particular about test cases.
56+
57+
Documentation
58+
-------------
59+
60+
Documentation on Source §x is generated from LaTeX sources in folder ``doc``.
61+
Currently the documents are generated as follows:
62+
``
63+
cd doc; make
64+
``
65+
66+
Documentation on the Source libraries are generated from inline documentation
67+
in the library sources. The libraries are in repository ``cadet-frontend``, which
68+
is assumed to be located in ``../cadet-frontend``, from the root of this repo.
69+
The documentation is generated as follows:
70+
``
71+
yarn run jsdoc
72+
``
73+
This command makes the documentation available in folder
74+
``
75+
doc/jsdoc/libraries/
76+
``
77+

‎doc/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@
33
*.pdf
44
*.out
55
*~
6+
Source

‎doc/README.md

Lines changed: 36 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,39 @@
1-
### Naming
2-
- The official specifications for Source § X is `source_X.pdf`.
3-
- Other `.tex` files are used as imports within the specs.
4-
- `source_week_X.pdf` is an *internal reference* for the staff, to aid with discussion groups.
1+
Source is a family of languages, designed for the textbook
2+
<a href="https://sicp.comp.nus.edu.sg">Structure and Interpretation
3+
of Computer Programs, JavaScript Adaptation</a> (SICP JS). The languages are
4+
called Source §1, Source §2, Source §3 and Source §4.
5+
corresponding to the respective chapters 1, 2, 3 and 4 of the
6+
textbook. Each previous Source language is a sublanguage of the
7+
next, and all Source languages are sublanguages of JavaScript.
8+
This webpage contains the description of the Source languages
9+
and the libraries they
10+
come with.
511

6-
### Generating PDFs
7-
Required for making the documents is a LaTeX installation.
12+
## <a href="source_1/">Source §1</a>
13+
14+
## <a href="source_2/">Source §2</a>
815

9-
Just try
10-
make
11-
in order to make the four documents
12-
source_1.pdf
13-
source_2.pdf
14-
source_3.pdf
15-
source_4.pdf
16-
source_styleguide.pdf
16+
## <a href="source_3/">Source §3</a>
1717

18-
If you get an error, try
19-
touch *.tex
20-
and try
21-
make
22-
again.
18+
## <a href="source_4/">Source §4</a>
19+
20+
## <a href="External libraries/">External Libraries</a>
21+
22+
The <a href="https://sourceacademy.nus.edu.sg">Source Academy</a>,
23+
a learning environment that uses SICP JS and Source, comes with the following
24+
<a href="External libraries/">external libraries</a>:
25+
26+
<ul>
27+
<li>
28+
<a href="RUNES/index.html">RUNES</a>: programming with rune graphics
29+
</li>
30+
<li>
31+
<a href="CURVES/index.html">CURVES</a>: programming with curve graphics
32+
</li>
33+
<li>
34+
<a href="SOUNDS/index.html">SOUNDS</a>: sound processing
35+
</li>
36+
<li>
37+
<a href="BINARYTREES/index.html">BINARYTREES</a>: binary trees
38+
</li>
39+
</ul>

‎doc/README_1.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
Source §1 is a small programming language, designed for the first chapter
2+
of the textbook
3+
<a href="https://sicp.comp.nus.edu.sg">Structure and Interpretation
4+
of Computer Programs, JavaScript Adaptation</a> (SICP JS).
5+
6+
## What names are predeclared in Source §1?
7+
8+
On the right, you see all predeclared names of Source §1, in alphabetical
9+
order. Click on a name to see how it is defined and used.
10+
These names come in two groups:
11+
<ul>
12+
<li>
13+
<a href="../MISC/index.html">MISC</a>: Miscellaneous constants and functions
14+
</li>
15+
<li>
16+
<a href="../MATH/index.html">MATH</a>: Mathematical constants and functions
17+
</li>
18+
</ul>
19+
In addition,
20+
<a href="https://sicp.comp.nus.edu.sg/chapters/33">section 2.2.4 SICP JS</a> makes
21+
use of <a href="../RUNES/index.html">RUNES</a>, a library for runes graphics.
22+
23+
## What can you do in Source §1?
24+
25+
You can use all features that are introduced in
26+
<a href="https://sicp.comp.nus.edu.sg/chapters/1">chapter 1</a> of the
27+
textbook. Below is the list of features, each with a link to the
28+
textbook section that introduces it and a small example.
29+
30+
### Literal values
31+
32+
Literal values are simple expressions that directly evaluate to values. These
33+
include numbers in the usual decimal notation, the two boolean values
34+
`true` and `false`, and the predeclared names
35+
`NaN`, `Infinity` and `undefined`.
36+
More on literal values in <a href="https://sicp.comp.nus.edu.sg/chapters/2">section
37+
1.1 The Elements of Programming</a> of the textbook.
38+
39+
### Constant declarations
40+
41+
Constant declarations are done in Source with <PRE><CODE>const my_name = x + 2;</CODE></PRE>
42+
Here the name `my_name` gets declared within the surrounding block,
43+
and refers to the result of evaluating `x + 2` in the rest of the block.
44+
You can read more about the <EM>scope of names</EM> in
45+
<a href="https://sicp.comp.nus.edu.sg/chapters/10">section 1.1.8
46+
Functions as Black-Box Abstractions</a>.
47+
48+
### Conditional statements and conditional expressions
49+
50+
Within expressions, you can let a <EM>predicate</EM> determine whether
51+
a <EM>consequent expression</EM>
52+
gets evaluated or an <EM>alternative expression</EM>. This is done by writing,
53+
for example
54+
<PRE><CODE>return p(x) ? 7 : f(y);</CODE></PRE>
55+
Read more on conditional expressions in
56+
<a href="https://sicp.comp.nus.edu.sg/chapters/8">section 1.1.6
57+
Conditional Expressions and Predicates</a>.
58+
<EM>Conditional evaluation</EM> is also possible within statements, for
59+
example the body of a function declaration. For that, you can use <EM>conditional
60+
statements</EM>, for example:<PRE><CODE>if (p(x)) {
61+
return 7;
62+
} else {
63+
return f(y);
64+
}</CODE></PRE>
65+
Read about <EM>conditional statements</EM> in
66+
<a href="https://sicp.comp.nus.edu.sg/chapters/20">section 1.3.2
67+
Function Definition Expressions</a>.
68+
69+
### Function declarations and function definitions
70+
71+
A function declaration is a statement that declares a name and binds it
72+
to a function. For example
73+
<PRE><CODE>function square(x) {
74+
return x * x;
75+
}</CODE>
76+
</PRE>
77+
declares the name `square` and binds it to a squaring function, so that it can be applied
78+
as in `square(5);`. You can read about function declaration statements in textbook
79+
<a href="https://sicp.comp.nus.edu.sg/chapters/6">section 1.1.4 Functions</a>.
80+
81+
Sometimes, it's not necessary to give a name to a function: You may
82+
want to create a function only to pass it to some other function as argument.
83+
For that, Source
84+
supports function definition expressions. For example
85+
<PRE><CODE>(x => x * x)(3); // returns 9</CODE>
86+
</PRE>
87+
creates a square function just like the function declaration above,
88+
but does not give it a name.
89+
Its only purpose it to be applied to the number 3. See also
90+
textbook
91+
<a href="https://sicp.comp.nus.edu.sg/chapters/20">section 1.3.2 Function Definition Expressions</a>.
92+
93+
### Blocks
94+
95+
Blocks make up the bodies of functions and the consequent and alternative statements of
96+
conditional statements. You can use blocks also elsewhere in your program, if you
97+
want to declare constants local to a specific scope. For example in this program
98+
<PRE><CODE>const a = 1;
99+
{
100+
const a = 2;
101+
display(a);
102+
}
103+
display(a);</CODE>
104+
</PRE>
105+
the first application of `display` shows the value 2, because the
106+
declaration <B>const</B> `a = 2;` re-declares the constant `a`.
107+
However, the second application
108+
of `display` shows the value 1, because
109+
the declaration <B>const</B> `a = 2;` is limited in scope by its surrounding block.
110+
You can read more about <EM>blocks</EM> in
111+
<a href="https://sicp.comp.nus.edu.sg/chapters/10">section 1.1.8
112+
Functions as Black-Box Abstractions</a>.
113+
114+
### Boolean operators
115+
116+
Boolean operators in Source have a special meaning. Usually, an operator combination
117+
evaluates all its arguments and then applies the operation to which the operator refers.
118+
For example, `(2 * 3) + (4 * 5)` evaluates `2 * 3` and `4 * 5` first, before the addition
119+
is carried out. However, the operator `&&` works differently. An expression
120+
`e1 && e2` should be seen as an abbreviation for `e1 ? e2 : false`. The expression
121+
`e2` only gets evaluated if `e1` evaluates to `true`. The behaviour of `||` is similar:
122+
`e1 || e2` should be seen as an abbreviation for `e1 ? true : e2`. More on these
123+
two boolean operators in textbook
124+
<a href="https://sicp.comp.nus.edu.sg/chapters/8">section 1.1.6 Conditional
125+
Expressions and Predicates</a>.
126+
127+
### Sequences
128+
129+
A program or the body of a block does not need to consist of a single statement.
130+
You can write multiple statements in a row. In the REPL ("Read-Eval-Print-Loop")
131+
of a Source implementation, you can write
132+
<PRE><CODE>cube(7);
133+
square(5);</CODE></PRE>
134+
The statements in such a sequence are evaluated in the given order. The
135+
result of evaluating the sequence is the result of evaluating the last
136+
statement in the sequence, in this case `square(5);`.
137+
Read more about sequences in
138+
<a href="https://sicp.comp.nus.edu.sg/chapters/4">section 1.1.2
139+
Naming and the Environment</a> of the textbook.
140+
141+
## You want the definitive specs?
142+
143+
For our development team, we are maintaining a definitive description
144+
of the language, called the
145+
<a href="../source_1.pdf">Specification of Source §1</a>. Feel free to
146+
take a peek.
147+

‎doc/README_2.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
Source §2 is a small programming language, designed for the second chapter
2+
of the textbook
3+
<a href="https://sicp.comp.nus.edu.sg">Structure and Interpretation
4+
of Computer Programs, JavaScript Adaptation</a> (SICP JS).
5+
6+
## What names are predeclared in Source §2?
7+
8+
On the right, you see all predeclared names of Source §2, in alphabetical
9+
order. Click on a name to see how it is used. They come in these three groups:
10+
<ul>
11+
<li>
12+
<a href="../MISC/">MISC</a>: Miscellaneous constants and functions
13+
</li>
14+
<li>
15+
<a href="../MATH/">MATH</a>: Mathematical constants and functions
16+
</li>
17+
<li>
18+
<a href="../LISTS/">LISTS</a>: Support for lists
19+
</li>
20+
</ul>
21+
22+
The <a href="https://sourceacademy.nus.edu.sg">Source Academy</a>,
23+
a learning environment that uses SICP JS and Source, comes with the following
24+
<a href="External libraries/">external libraries</a>:
25+
<ul>
26+
<li>
27+
<a href="../RUNES/index.html">RUNES</a>: Library for runes graphics
28+
</li>
29+
<li>
30+
<a href="../CURVES/index.html">CURVES</a>: Library for curve graphics
31+
</li>
32+
<li>
33+
<a href="../SOUNDS/index.html">SOUNDS</a>: Library for sound processing
34+
</li>
35+
<li>
36+
<a href="../BINARYTREES/index.html">BINARYTREES</a>: Library for binary trees
37+
</li>
38+
</ul>
39+
40+
## What can you do in Source §2?
41+
42+
You can use all features of
43+
<a href="../Source §1/">Source §1</a> and all
44+
features that are introduced in
45+
<a href="https://sicp.comp.nus.edu.sg/chapters/23">chapter 2</a> of the
46+
textbook.
47+
Below are the features that Source §2 adds to Source §1.
48+
49+
### The empty list `null`
50+
51+
Source §2 provides a new primitive value, `null`, that serves as empty list.
52+
53+
### The LIST functions
54+
55+
To work with lists, you can use the functions in the
56+
<a href="../LISTS/">LISTS</a> group of predeclared functions, already mentioned
57+
above.
58+
59+
## You want the definitive specs?
60+
61+
For our development team, we are maintaining a definitive description
62+
of the language, called the
63+
<a href="../source_2.pdf">Specification of Source §2</a>. Feel free to
64+
take a peek!
65+
66+

0 commit comments

Comments
 (0)