Updated About SMNP Language (markdown)

About-SMNP-Language.md

@@ -28,4 +28,49 @@ However, if you switch `x` value to `true`, error will be thrown when
 control flow reaches `foo` function invocation with wrong argument's type.
 Even though there is no real definition of strongly-typed language,
 we can say SMNP is strongly-typed, because there are no any implicit type
-coercion. You always have to provide correct, expected type.
+coercion. You always have to provide correct, expected type.
+
+# Comments
+SMNP language allows you to make comments in the code.
+It can be done with # character, like:
+```
+# This is a comment
+```
+There is no syntax for multiline comment, but you can of course do something like this:
+```
+# This is
+# a multiline
+# comment
+```
+Note that because of hash-beginning comments you can
+put a shebang at the very first of your code making it more
+convenient to execute:
+```
+#!/usr/bin/smnp
+println("Hello, world!");
+
+# And now add executable flag (chmod +x) 
+# to the file and execute it like any other 
+# script/program from the shell 
+```
+# Instruction terminator
+SMNP language doesn't require you to delimit instructions, however it is still possible
+and highly recommended, because it helps you to get rid of code ambiguity.
+
+Example:
+```
+size = [1, 2, 3].size
+(size - 1) as i ^ print(i)
+```
+Execution of this code is interrupted with error, because SMNP parser
+tries to interpret size property as method `[1, 2, 3].size(size - 1)`.
+As long as lists don't have size method (but they have size property),
+error will be raised and you will be able to fix problem. However, ambiguity could be
+a less obvious and you can stick with debugging code having no idea what is going wrong.
+To remove ambiguity you can end each instruction with semicolon `;`:
+```
+size = [1, 2, 3].size;
+(size - 1) as i ^ print(i);  # 01
+```
+All code snippets of present document follows the convention of ending each
+instruction with semicolon.