Updated the doc comments text.

src/content/docs/FAQ/allfeatures.md

@@ -338,8 +338,8 @@ but nonetheless provided unique functionality:
 
 ## Contracts
 
-1. Doc comments (starting with `<*`) are parsed.
-2. The first part, up until the first `@` directive is ignored.
+1. Doc contracts (starting with `<*`) are parsed.
+2. The first part, up until the first `@` directive on a new line, is ignored.
 3. The `@param` directive for pointer arguments may define usage constraints `[in]` `[out]` and `[inout]`.
 4. Pointer argument constraints may add a `&` prefix to indicate that they may not be `null`, e.g. `[&inout]`.
 5. Contracts may be attached to generic modules, functions and macros.

src/content/docs/Implementation Details/specification.md

@@ -43,13 +43,13 @@ A program consists of one or more _translation units_ stored in files written in
 stored as a sequence of bytes using the UTF-8 encoding. Except for comments and the contents of character and string
 literals, all input elements are formed only from the ASCII subset (U+0000 to U+007F) of Unicode.
 
-A raw byte stream is translated into a sequence of tokens which white space and non-doc comments are discarded. Doc
+A raw byte stream is translated into a sequence of tokens which white space and comments are discarded. Doc
 comments may optionally be discarded as well. The resulting input elements form the tokens that are the terminal symbols
 of the syntactic grammar.
 
 ### Lexical Translations
 
-A raw byte stream is translated into a sequence of tokens which white space and non-doc comments are discarded. Doc
+A raw byte stream is translated into a sequence of tokens which white space and comments are discarded. Doc
 comments may optionally be discarded as well. The resulting input elements form the tokens that are the terminal symbols
 of the syntactic grammar.
 
@@ -71,7 +71,7 @@ An input element may be:
 
 1. White space
 2. Comment
-3. Doc Comment
+3. Doc Contract
 4. Token
 
 A token may be:
@@ -82,7 +82,7 @@ A token may be:
 4. Separator
 5. Operator
 
-A Doc Comment consists of:
+A Doc Contract consists of:
 
 1. A stream of descriptive text
 2. A list of directive Tokens
@@ -127,7 +127,7 @@ There are three types of regular comments:
 2. `/* text */` block comments. The text between `/*` and `*/` is ignored. It has nesting behaviour, so for every `/*`
    discovered between the first `/*` and the last `*/` a corresponding `*/` must be found.
 
-### Doc comments
+### Doc contract
 
 1. `<* text *>` doc block comment. The text between `<*` and `*>` is optionally parsed using the doc comment
    syntactic grammar. A compiler may choose to read `<* text *>` as a regular comment.

src/content/docs/Language Fundamentals/comments.md

@@ -10,9 +10,11 @@ C3 uses three distinct comment types:
 2. The classic `/* ... */` multi-line C style comment, but unlike in C they are allowed to nest.
 3. Documentation comments `<* ... *>` the text within these comments will be parsed as documentation and optional [Contracts](/language-common/contracts/) on the following code.
 
-## Doc Comments
+## Doc contracts
 
-Documentation comments start with `<*` and must be terminated using `*>`. Note that any number of `*` may follow `<*` and any number of stars may preceed `*>`. Any space and `*` in the beginning of each line will be ignored.
+Documentation contracts start with `<*` and must be terminated using `*>`.
+Any initial text up until the first `@`-directive on a new line will be interpreted as
+free text documentation.
 
 For example:
 
@@ -30,7 +32,7 @@ void bar(int num_foo)
 }
 ```
 
-### Doc Comments Are Parsed
+### Doc Contracts Are Parsed
 The following was extracted:
 - The function description: *"Here are some docs."*
 - The `num_foo` parameter has the description: *"The number of foos"*.

src/content/docs/Language Overview/primer.md

@@ -308,7 +308,7 @@ The `/* */` comments are nesting
 /* This /* will all */ be commented out */
 ```
 
-Note that doc comments starting with `<*` and ending with `*>`, have special rules for parsing them, and are
+Note that doc contracts starting with `<*` and ending with `*>`, have special rules for parsing them, and are
 _not_ considered a regular comment. Find out more about [contracts](/language-common/contracts/).
 
 ## Type Qualifiers