#19-Create Typee language documentation

Function call subsection added. Lead to corrections in formerly written text.

html-content/documentation-3-10-functions.html

@@ -11,10 +11,12 @@ <h3>3.10 - Functions</h3>
 Finally, functions (and methods as well) may be overloaded and overridden. We will explain what does this mean, later in this section.
 
 The overall formal EBNF specification of functions (and methods) rules in <strong>Typee</strong> are:
-<pre>&lt;function call&gt;             ::= &lt;identifier&gt;
+<pre>&lt;function call statement&gt;   ::= &lt;function call&gt; '<strong>;</strong>'
+
+&lt;function call&gt;             ::= &lt;dotted name&gt;
                                     [&lt;template args&gt;] '<strong>(</strong>' &lt;function call args&gt; '<strong>)</strong>' 
 
-&lt;function declaration&gt;      ::= &lt;forward&gt; &lt;function decl&gt;
+&lt;function declaration&gt;      ::= &lt;forward&gt; &lt;function decl&gt; '<strong>;</strong>'
 
 &lt;function definition&gt;       ::= &lt;function decl&gt; &lt;statements block&gt;
 
@@ -23,14 +25,11 @@ <h3>3.10 - Functions</h3>
 
 &lt;call operator&gt;             ::= '<strong>(</strong>' '<strong>)</strong>' 
 
-&lt;forward&gt;                   ::= '<strong>ret</strong>' | '<strong>return</strong>' 
+&lt;forward&gt;                   ::= '<strong>forward</strong>' | '<strong>fwd</strong>' 
 
 &lt;function args declaration&gt; ::= '<strong>(</strong>' [&lt;typed args list&gt;] '<strong>)</strong>' 
 
-&lt;function call args&gt;        ::= [ &lt;expression&gt; (&lt;function call&gt;)*
-                                    [ '<strong>,</strong>' ( &lt;expression&gt; (&lt;function call&gt;)*  |
-                                            '<strong>...</strong>' &lt;identifier&gt; )  |
-                                      &lt;for comprehension&gt;] ]
+&lt;function call args&gt;        ::= [ &lt;expression&gt; ('<strong>,</strong>' &lt;expression&gt;)* ]
 
 &lt;function decl&gt;             ::= [&lt;access protection qualifier&gt;] ['<strong>final</strong>']
                                     &lt;type&gt; &lt;identifier&gt;
@@ -114,7 +113,7 @@ <h4>3.10.1 Function Definition</h4>
 
 As a reminder, visibility qualifiers in Typee are:
 <pre>&lt;access protection qualifier&gt; ::= '<strong>hidden</strong>' | '<strong>local</strong>' | '<strong>private</strong>'
-                                     '<strong>protected</strong>' | '<strong>public</strong>'
+                                  '<strong>protected</strong>' | '<strong>public</strong>'
 </pre>
 
 &nbsp;
@@ -180,10 +179,55 @@ <h4>3.10.1 Function Definition</h4>
 &nbsp;
 <h4>3.10.2 Function Declaration</h4>
 
+In <strong>Typee</strong>, functions may only be declared in a forward statement. The only need to declare a function is when it is to be defined in a module <em>after</em> it is called in this same module. Unnamed functions have not to be declared also. They are always defined at the place they are called.
+
+The formal EBNF sepcification of a function declaration is then:
+<pre>&lt;function declaration&gt; ::= &lt;forward&gt; &lt;function decl&gt; '<strong>;</strong>'
+&lt;forward&gt;              ::= '<strong>forward</strong>' | '<strong>fwd</strong>' 
+</pre>
+
+Since the funcion is only declared there, no statements block (i.e. function body) is allowed after the declaration of the signature of the function. This declaration bieng a statement, it has to be ended with a semi-colon. Very simple.
+
+Such declarations help Typee translators to check types and functions signatures when they are called with no delay (this is a not-lazy evaluation or checking of types and signatures).
+
 
 &nbsp;
 <h4>3.10.3 Function Call</h4>
 
+Functions are called with values or references as arguments. The types of the arguments define part of the signature of the function to be called. The other part of the signature is the type of its returned value. In case of possible ambiguities about returned type, <strong>Typee</strong> translators will set an explicit warning or even erro acording to the contextr. This is discussed in a next paragraph.
+
+Let's first describe the formal EBNF specification of functions calls:
+<pre>&lt;function call&gt;       ::= &lt;identifier&gt;
+                              [&lt;template args&gt;] '<strong>(</strong>' &lt;function call args&gt; '<strong>)</strong>' 
+
+&lt;function call args&gt;  ::= [ &lt;expression&gt; ('<strong>,</strong>' &lt;expression&gt;)* ]
+</pre>
+
+The <strong>identifier</strong> is the identifier of the function.
+It may be followed by <strong>template arguments</strong> if declared or defined so. Notice: templates arguments are enclosed within angle brackets <code style="font-size:115%;font-weght:bold;">&lt;</code> and <code style="font-size:115%;font-weght:bold;">&gt;</code> and are lists of types or constant values - more about templates later in this documentation.
+Next are the values, variables or references passed as arguments to the function at call-time. These arguments are seperated by commas and are enclosed between parenthesis: <code style="font-size:115%;font-weght:bold;">(</code> and <code style="font-size:115%;font-weght:bold;">)</code>. Their number and the ordered list of their types are part of the signature of the called function. Should any ambiguity be found at translation time, <strong>Typee</strong> translators will set an explicit error.
+
+Finally, to fully evaluate the signature of the called function, its returned type is evaluated at translation time.
+
+A function that returns no value can only be called in a <strong style="font-size:105%;">function call statement</code>:
+<pre>&lt;function call statement&gt; ::= &lt;function call&gt; '<strong>;</strong>'
+</pre>
+When a no-value returning function will be called in any arithmetic expression, assignment statement and conditional expression, <strong>Typee</strong> translators will set a type error.
+
+The type of the value returned by a called function will be inferred at translation time, according to the context of the call. Most of the time, this will be straightforward to evaluate. For instance, when assigning a variable with the result of a function the type of the assigned variable will be used for the type inferrence. Or, when calling a function in an arithmetic or conditional expression, the inferred type for returned type of the called function will be the type of the other terms in the evaluated expression.
+
+Meanwhile, it may happen that according to a same function identifier and types of arguments list, a couple of returned types could be inferred for the called function - see simple example below. <strong>Typee</strong> translators will then:
+<ul>
+    <li>either set a warning if all the possibly inferred returned types are all compatible together and with the expected type in the expression or assignment (e.g. integers and floats), informing that the <em>largest</em> type will be used:
+        <ol>
+          <li>floats first, 64-bits before 32-bits</li>;
+          <li>integers then, in this order: 64-, 32-, 16- and then 8- bits; signed types before unsigned types if any of the other types inferred in the expression cannot be clearly inferred as unsigned</li>;
+        <ol></li>
+    <li>or set an error if possibly inferred returned types are not compatible with the expectedtype</li>.
+</ul>
+
+Programmers are informed here that they should avoid as much as possible any ambiguity with signatures of called functions. Programming languages such as <em>C++</em> or <em>Java</em> do not allow functions with same identifier to return different types of values. <strong>Typee</strong> allows this. It is simply processed at translation time when translating Typee code to programming languages that do not allow it. Then, programmers have to be careful when using this Typee goody with such not permissive programming languages.
+
 
 &nbsp;
 <h4>3.10.5 Unnamed Functions</h4>