Merge pull request GaijinEntertainment#1926 from GaijinEntertainment/new-documentation

updating documentation to new generator

Author: borisbat

daslib/algorithm.das

@@ -77,10 +77,12 @@ def lower_bound(a : array<auto(TT)>; f, l : int; val : TT const -&) {
 }
 
 def lower_bound(a : array<auto(TT)>; val : TT const -&) {
+    //! Returns an iterator pointing to the first element in the array that is not less than (i.e. greater or equal to) value, or length(a) if no such element is found.
     return lower_bound(a, 0, length(a), val)
 }
 
 def lower_bound(a : array<auto(TT)>; f, l : int; value : auto(QQ); less : block<(a : TT const -&, b : QQ) : bool>) {
+    //! Returns an iterator pointing to the first element in the range [first, last) that is not less than (i.e. greater or equal to) value, or last if no such element is found.
     assert(f >= 0 && f <= l, "lower bound first out of range")
     assert(l >= f && l <= length(a), "lower bound last out of range")
     var count = l - f
@@ -99,10 +101,13 @@ def lower_bound(a : array<auto(TT)>; f, l : int; value : auto(QQ); less : block<
 }
 
 def lower_bound(a : array<auto(TT)>; value : auto(QQ); less : block<(a : TT const -&, b : QQ) : bool>) {
+    //! Returns an iterator pointing to the first element in the array that is not less than (i.e. greater or equal to) value, or length(a) if no such element is found.
     return lower_bound(a, 0, length(a), value, less)
 }
 
 def binary_search(a : array<auto(TT)>; val : TT const -&) {
+    //! Returns true if an val appears within the array a.
+    //! Array a must be sorted.
     let first = lower_bound(a, val)
     return (first != length(a)) && (!(val < a[first]))
 }
@@ -115,12 +120,16 @@ def binary_search(a : array<auto(TT)>; f, last : int; val : TT const -&) {
 }
 
 def binary_search(a : array<auto(TT)>; val : TT const -&; less : block<(a, b : TT const -&) : bool>) {
+    //! Returns true if an val appears within the array a.
+    //! Array a must be sorted according to the provided less function.
     let first = lower_bound(a, val, less)
     let last = length(a)
     return (first != last) && (!invoke(less, val, a[first]))
 }
 
 def binary_search(a : array<auto(TT)>; f, last : int; val : TT const -&; less : block<(a, b : TT const -&) : bool>) {
+    //! Returns true if an val appears within the range [f, last).
+    //! Array a must be sorted according to the provided less function.
     let first = lower_bound(a, f, last, val, less)
     return (first != last) && (!invoke(less, val, a[first]))
 }
@@ -129,20 +138,23 @@ def binary_search(a : array<auto(TT)>; f, last : int; val : TT const -&; less :
 
 [expect_any_array(a)]
 def reverse(var a) {
+    //! Reverses the elements of array a in place.
     unsafe {
         reverse(temp_array(a))
     }
 }
 
 [expect_any_array(a)]
 def combine(a, b) {
+    //! Returns array of the elements of a and then b.
     unsafe {
         return combine(temp_array(a), temp_array(b))
     }
 }
 
 [expect_any_array(a)]
 def lower_bound(a; f, l : int; val) {
+    //! Returns an iterator pointing to the first element in the range [first, last) that is not less than (i.e. greater or equal to) value, or last if no such element is found.
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -155,6 +167,7 @@ def lower_bound(a; f, l : int; val) {
 
 [expect_any_array(a)]
 def lower_bound(a; val) {
+    //! Returns an iterator pointing to the first element in the array that is not less than (i.e. greater or equal to) value, or length(a) if no such element is found.
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -167,6 +180,7 @@ def lower_bound(a; val) {
 
 [expect_any_array(a)]
 def lower_bound(a; f, l : int; val : auto(TT); less : block<(a, b : TT const -&) : bool>) {
+    //! Returns an iterator pointing to the first element in the range [first, last) that is not less than (i.e. greater or equal to) value, or last if no such element is found.
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -179,6 +193,7 @@ def lower_bound(a; f, l : int; val : auto(TT); less : block<(a, b : TT const -&)
 
 [expect_any_array(a)]
 def lower_bound(a; val : auto(TT); less : block<(a, b : TT const -&) : bool>) {
+    //! Returns an iterator pointing to the first element in the array that is not less than (i.e. greater or equal to) value, or length(a) if no such element is found.
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -191,6 +206,7 @@ def lower_bound(a; val : auto(TT); less : block<(a, b : TT const -&) : bool>) {
 
 [expect_any_array(a)]
 def binary_search(a; val) {
+    //! Returns true if an val appears within the array a.
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -203,6 +219,7 @@ def binary_search(a; val) {
 
 [expect_any_array(a)]
 def binary_search(a; f, last : int; val) {
+    //! Returns true if an val appears within the range [f, last).
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -215,6 +232,7 @@ def binary_search(a; f, last : int; val) {
 
 [expect_any_array(a)]
 def binary_search(a; val : auto(TT); less : block<(a, b : TT const -&) : bool>) {
+    //! Returns true if an val appears within the array a.
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1
@@ -227,6 +245,7 @@ def binary_search(a; val : auto(TT); less : block<(a, b : TT const -&) : bool>)
 
 [expect_any_array(a)]
 def binary_search(a; f, last : int; val : auto(TT); less : block<(a, b : TT const -&) : bool>) {
+    //! Returns true if an val appears within the range [f, last).
     static_if (typeinfo stripped_typename(a[0]) != typeinfo stripped_typename(val)) {
         concept_assert(false, "value type {typeinfo stripped_typename(val)} should be the same as array {typeinfo stripped_typename(a)} element type {typeinfo stripped_typename(a[0])}")
         return -1

daslib/archive.das

@@ -28,6 +28,7 @@ class public MemSerializer : Serializer {
         pass    // writing
     }
     def MemSerializer(from : array<uint8>) {
+        //! Initialize the serializer for reading from the given data.
         data := from
     }
     def extractData : array<uint8> {
@@ -75,16 +76,16 @@ class public MemSerializer : Serializer {
         //! Sets the last error code.
         lastError = code
     }
-    private data : array<uint8>
-    private readOffset : int
-    private lastError : string
+    private data : array<uint8> //! internal data buffer
+    private readOffset : int    //! current reading offset
+    private lastError : string  //! last error code
 }
 
 struct public Archive {
     //! Archive is a combination of serialization stream, and state (version, and reading status).
-    version : uint
-    reading : bool
-    stream  : Serializer?
+    version : uint //! Version of the archive format.
+    reading : bool //! True if the archive is for reading, false for writing.
+    stream  : Serializer? //! Serialization stream.
 }
 
 def public serialize_raw(var arch : Archive; var value : auto(TT)&) {
@@ -116,6 +117,7 @@ def public serialize(var arch : Archive; var value : auto(TT)&) {
 
 [expect_any_function(value)]
 def public serialize(var arch : Archive; var value : auto(TT)&) {
+    //! Serializes function pointer by its mangled name hash.
     if (arch.reading) {
         var mnh : uint64
         arch |> read_raw(mnh)
@@ -131,19 +133,23 @@ def public serialize(var arch : Archive; var value : auto(TT)&) {
 }
 
 def public serialize(var arch : Archive; var value : float3x3) {
+    //! Serializes float3x3 matrix
     arch |> serialize_raw(value)
 }
 
 def public serialize(var arch : Archive; var value : float3x4) {
+    //! Serializes float3x4 matrix
     arch |> serialize_raw(value)
 }
 
 def public serialize(var arch : Archive; var value : float4x4) {
+    //! Serializes float4x4 matrix
     arch |> serialize_raw(value)
 }
 
 [expect_any_struct(value)]
 def public serialize(var arch : Archive; var value : auto(TT)&) {
+    //! Serializes struct by serializing each field.
     if (arch.reading) {
         delete value
     }
@@ -154,6 +160,7 @@ def public serialize(var arch : Archive; var value : auto(TT)&) {
 
 [expect_any_tuple(value)]
 def public serialize(var arch : Archive; var value : auto(TT)&) {
+    //! Serializes tuple by serializing each field.
     if (arch.reading) {
         delete value
     }
@@ -164,6 +171,7 @@ def public serialize(var arch : Archive; var value : auto(TT)&) {
 
 [expect_any_variant(value)]
 def public serialize(var arch : Archive; var value : auto(TT)&) {
+    //! Serializes variant by serializing the index and the active field.
     if (arch.reading) {
         delete value
         var index : int
@@ -181,12 +189,14 @@ def public serialize(var arch : Archive; var value : auto(TT)&) {
 }
 
 def public serialize(var arch : Archive; var value : auto(TT)[]) {
+    //! Serializes array by serializing its length and each element.
     for (element in value) {
         arch |> _::serialize(element)
     }
 }
 
 def public serialize(var arch : Archive; var value : array<auto(TT)>) {
+    //! Serializes array by serializing its length and each element.
     if (arch.reading) {
         var len : int
         unsafe {
@@ -207,6 +217,7 @@ def public serialize(var arch : Archive; var value : array<auto(TT)>) {
 }
 
 def public serialize(var arch : Archive; var value : table<auto(KT); auto(VT)>) {
+    //! Serializes table by serializing its length and each key-value pair.
     if (arch.reading) {
         var len : int
         arch |> read_raw(len)
@@ -228,6 +239,7 @@ def public serialize(var arch : Archive; var value : table<auto(KT); auto(VT)>)
 }
 
 def public serialize(var arch : Archive; var value : string&) {
+    //! Serializes string by serializing its length and characters.
     unsafe {
         if (arch.reading) {
             var len : int
@@ -253,6 +265,7 @@ def public serialize(var arch : Archive; var value : string&) {
 }
 
 def public serialize(var arch : Archive; var value : auto(TT)?) {
+    //! Serializes nullable type by serializing a flag and the value if present.
     if (arch.reading) {
         value = null
     }

daslib/array_boost.das

@@ -12,6 +12,7 @@ require daslib/contracts
 
 [unsafe_operation, template(a), unused_argument(a)]
 def private array_helper(var arr : auto implicit ==const; a : auto(TT)) : array<TT -const -#> {
+    //! helper for temp_array with var argument
     var res : array<TT -const -#>
     let lenA = _::length(arr)
     if (lenA >= 1) {
@@ -24,6 +25,7 @@ def private array_helper(var arr : auto implicit ==const; a : auto(TT)) : array<
 
 [unsafe_operation, template(a), unused_argument(a)]
 def private array_helper(arr : auto implicit ==const; a : auto(TT)) : array<TT -const -#> {
+    //! helper for temp_array with const argument
     var res : array<TT -const -#>
     let lenA = _::length(arr)
     if (lenA >= 1) {
@@ -48,6 +50,11 @@ def public temp_array(var arr : auto implicit ==const) {
 
 [unsafe_operation]
 def public temp_array(arr : auto implicit ==const) {
+    //! Creates temporary array from the given object.
+    //! Important requirements are:
+    //!     * object memory is linear
+    //!     * each element follows the next one directly, with the stride equal to size of the element
+    //!     * object memory does not change within the lifetime of the returned array
     unsafe {
         return <- array_helper(arr, decltype(arr[0]))
     }
@@ -61,6 +68,11 @@ def empty(v : auto(VecT)) {
 
 [unsafe_operation, template(a), unused_argument(a)]
 def public temp_array(var data : auto? ==const; lenA : int; a : auto(TT)) : array<TT -const -#> {
+    //! creates a temporary array from the given data pointer and length
+    //! Important requirements are:
+    //!     * data pointer is valid and points to a memory block of at least lenA elements
+    //!     * each element follows the next one directly, with the stride equal to size of the element
+    //!     * data memory does not change within the lifetime of the returned array
     var res : array<TT -const -#>
     if (lenA >= 1) {
         unsafe {
@@ -72,6 +84,11 @@ def public temp_array(var data : auto? ==const; lenA : int; a : auto(TT)) : arra
 
 [unsafe_operation, template(a), unused_argument(a)]
 def public temp_array(data : auto? ==const; lenA : int; a : auto(TT)) : array<TT -const -#> const {
+    //! creates a temporary array from the given data pointer and length
+    //! Important requirements are:
+    //!     * data pointer is valid and points to a memory block of at least lenA elements
+    //!     * each element follows the next one directly, with the stride equal to size of the element
+    //!     * data memory does not change within the lifetime of the returned array
     var res : array<TT -const -#>
     if (lenA >= 1) {
         unsafe {

daslib/ast_used.das

@@ -10,44 +10,42 @@ require daslib/ast_boost
 
 struct public OnlyUsedTypes {
     //! Collection of all structure and enumeration types that are used in the AST.
-    st : table<Structure?; bool>
-    en : table<Enumeration?; bool>
+    st : table<Structure?>   //! all structure types used
+    en : table<Enumeration?>   //! all enumeration types used
 }
 
 class TypeVisitor : AstVisitor {
-    usedTypes : OnlyUsedTypes
+    usedTypes : OnlyUsedTypes //! collected used types
     def TypeVisitor {
         pass
     }
     def collect(typ : TypeDeclPtr) {
-        unsafe {
-            if (typ.baseType == Type.tStructure) {
-                if (usedTypes.st |> key_exists(reinterpret<Structure?> typ.structType)) {
-                    return
-                }
-            }
-            if (typ.structType != null) {
-                usedTypes.st[reinterpret<Structure?> typ.structType] = true
-                for (fld in typ.structType.fields) {
-                    self->collect(fld._type)
-                }
+        if (typ.baseType == Type.tStructure) {
+            if (usedTypes.st |> key_exists(typ.structType)) {
+                return
             }
-            if (typ.enumType != null) {
-                usedTypes.en[reinterpret<Enumeration?> typ.enumType] = true
+        }
+        if (typ.structType != null) {
+            insert(usedTypes.st, typ.structType)
+            for (fld in typ.structType.fields) {
+                collect(fld._type)
             }
         }
+        if (typ.enumType != null) {
+            insert(usedTypes.en, typ.enumType)
+        }
         if (typ.firstType != null) {
-            self->collect(typ.firstType)
+            collect(typ.firstType)
         }
         if (typ.secondType != null) {
-            self->collect(typ.secondType)
+            collect(typ.secondType)
         }
         for (arg in typ.argTypes) {
-            self->collect(arg)
+            collect(arg)
         }
     }
     def override preVisitTypeDecl(typ : TypeDeclPtr) : void {
-        self->collect(typ)
+        collect(typ)
     }
 }
 

daslib/coroutines.das

@@ -11,9 +11,9 @@ require daslib/templates_boost
 require daslib/macro_boost
 require daslib/defer
 
-typedef Coroutine = iterator<bool>
-typedef Coroutines = array<Coroutine>
+typedef Coroutine = iterator<bool> //! A coroutine is a generator that yields bool to indicate if it is still running.
 
+typedef Coroutines = array<Coroutine> //! An array of coroutines.
 
 [call_macro(name="yeild_from")]
 class private YieldFrom : AstCallMacro {