Чистка справки OpenCLABC

Packing/Spec/CL ABC/0#Общие сведения/1#Термины, которые часто путают новички.md

@@ -1,21 +1,21 @@
 
 
 
-- CPU — Центральное Процессорное Устройство (процессор)
+- CPU — Центральное Процессорное Устройство (процессор);
 
-- GPU — Графическое Процессорное Устройство (видеокарта)
+- GPU — Графическое Процессорное Устройство (видеокарта);
 
 - Команда — запрос на выполнение чего-либо. К примеру:
-	- Запрос на запуск программы на GPU
-	- Запрос на начало чтения данных из памяти GPU в оперативную память
+	- Запрос на запуск программы на GPU;
+	- Запрос на начало чтения данных из памяти GPU в оперативную память;
 
 	**Называть процедуры и функции командами ошибочно!**
 
-- Подпрограмма — процедура или функция
+- Подпрограмма — процедура или функция;
 
-- Метод — особая подпрограмма, вызываемая через экземпляр
-	- К примеру, метод `Context.SyncInvoke` выглядит в коде как `cont.SyncInvoke(...)`, где `cont` — переменная типа `Context`
+- Метод — особая подпрограмма, вызываемая через экземпляр:
+	- К примеру, метод `Context.SyncInvoke` выглядит в коде как `cont.SyncInvoke(...)`, где `cont` — переменная типа `Context`;
 
-Остальные непонятные термины можно найти в справке `PascalABC.NET` или в интернете
+Остальные непонятные термины можно найти в справке `PascalABC.NET` или в интернете.
 
 

Packing/Spec/CL ABC/1#Контекст (Context)/.md

@@ -21,7 +21,7 @@
 
 `Context.Default` можно перезаписывать.
 
-Используйте эту возможность только если во всей программе нужет общий контекст, но не стандартный.
+Используйте эту возможность только если во всей программе нужен общий контекст, но не стандартный.
 
 Частая перезапись `Context.Default` может привести к созданию сложно-ловимых багов в ваших программах.
 

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/2#Из готового результата.md

@@ -15,6 +15,8 @@ if cq=nil then
   Writeln($'Очередь была создана из значения {cq.Val}');
 ```
 
+---
+
 `CommandQueueBase` также можно создать из значения, но для этого тип значения должен быть `Object`:
 ```
 var q: CommandQueueBase := 5 as object;

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/3#С кодом для CPU.md

@@ -5,7 +5,7 @@
 А разрывать для этого очередь на две части - плохо, потому что
 одна целая очередь всегда выполнится быстрее двух её частей.
 
-Для таких случае существуют глобальные подпрограммы HFQ и HPQ:
+Для таких случае существуют глобальные подпрограммы `HFQ` и `HPQ`:
 
 HFQ — Host Function Queue\
 HPQ — Host Procedure Queue\
@@ -14,7 +14,7 @@ HPQ — Host Procedure Queue\
 Они возвращают очередь, выполняющую код (функцию/процедуру соотвественно) на CPU.\
 Подробнее уже описано
 <a path="../Возвращаемое значение очередей/">
-на предыдущей странице
+на странице выше
 </a>
 .
 

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/4#Комбинируя другие очереди.md

@@ -19,7 +19,8 @@ begin
   
   var q1 := HPQ(()->
   begin
-    // lock необходим чтобы при параллельном выполнении два потока не пытались использовать вывод одновременно. Иначе выведет кашу
+    // lock необходим чтобы при параллельном выполнении два потока
+    // не пытались использовать вывод одновременно. Иначе выведет кашу
     lock output do Writeln('Очередь 1 начала выполняться');
     Sleep(500);
     lock output do Writeln('Очередь 1 закончила выполняться');
@@ -67,11 +68,11 @@ begin
   // А точнее их перегрузку, первый параметр которой - функция преобразования
   Context.Default.SyncInvoke(
     CombineSyncQueue(
-      results->results.JoinIntoString, // функция преобразования
+      results->results.JoinToString, // функция преобразования
       q1, q2
     )
   ).Println;
-  // Теперь выводит строку "1 2". Это то же самое, что вернёт "Arr(1,2).JoinIntoString"
+  // Теперь выводит строку "1 2". Это то же самое, что вернёт "Arr(1,2).JoinToString"
   
 end.
 ```

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/5#Из очереди + преобразователя.md

@@ -32,7 +32,8 @@ Context.Default.SyncInvoke( Q4.Cast&<t2> );
 Context.Default.SyncInvoke( Q5.Cast&<t1> );
 ```
 
-Ну а если эти ограничения не подходят - остаётся только `.ThenConvert`. Он позволяет указать любой алгоритм преобразования, но и требует бОльшей производительности:
+Ну а если эти ограничения не подходят - остаётся только `.ThenConvert`.
+Он позволяет указать любой алгоритм преобразования, но работает медленнее:
 ```
 uses OpenCLABC;
 

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/8#Особые .Add методы.md

@@ -32,13 +32,13 @@ var q := b.NewQueue
 
 Эти методы не имеют незаменимых применений, но позволяют сделать код значительно читабельнее.
 
-Кроме того, будьте осторожны, защиты от дурака для такого случая - отсутствует:
+Кроме того, будьте осторожны, защита от дурака для такого случая - отсутствует:
 ```
 var q := b.NewQueue;
 q.AddQueue(q);
 ```
 Все `.Add*` методы добавляют команды в существующую очередь, а не создают новую.
 Поэтому очередь, созданная предыдущим кодом при попытке выполнения начнёт циклически запускать саму себя.
-Но это вызовет скорее не зависание, а переполнение стека (что, в целом, не лучше).
+Но это вызовет скорее не зависание, а переполнение стека (что, впрочем, не лучше).
 
 

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/9#Из ожидания очередей.md

@@ -121,7 +121,7 @@ begin
   
   var t1 := Context.Default.BeginInvoke(
     WaitFor(Q1) +
-    WaitFor(Q1) // второго запуска Q1 никогда не произойдёт, поэтому это зависнет
+    WaitFor(Q1) // второй запуск Q1 никогда не произойдёт, поэтому это зависнет
   );
   Context.Default.BeginInvoke(Q1);
   
@@ -131,7 +131,7 @@ end.
 
 ---
 
-Cчётчик создаётся для каждой пары [ожидаемой очереди] и [вызова `Context.BeginInvoke`] для ожидающей очереди.
+Cчётчик создаётся для каждой пары [ожидаемой очереди] и [вызова `Context.BeginInvoke` с ожидающей очередью].
 То есть это тоже сработает:
 ```
 uses OpenCLABC;
@@ -191,6 +191,6 @@ end.
 ---
 
 И последнее что надо знать - `Wait-Any` очередь хоть и ожидает выполнения любой одной очереди из списка,
-но отнимает 1 от счётчиков всех ожидаемых очередей из того списка.
+но отнимает 1 от счётчиков всех ожидаемых очередей из своего списка.
 
 

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/2#Создание очередей/91#Не создавая явно.md

@@ -5,8 +5,8 @@
 Но нередко бывает так, что команда всего одна. Или для отладки надо одноразово выполнить одну команду.
 
 Для таких случаев можно создавать очередь неявно:\
-У каждого метода очереди, создаваемой с `.NewQueue` есть дублирующий метод в оригинальном объекте.
-Такие методы сами создают новую очередь, добавляют в неё одну соответствующую команду и выполняют полученную очередь в `Context.Default.SyncInvoke(...)`.
+У каждого `.Add*` метода есть дублирующий метод в оригинальном объекте. Такие методы сами создают
+новую очередь, добавляют в неё одну соответствующую команду и выполняют полученную очередь в `Context.Default.SyncInvoke(...)`.
 
 Обычный код с очередями:
 ```
@@ -61,10 +61,10 @@ begin
 end.
 ```
 
-Кроме того, у типа `Buffer` есть дополнительные методы `Buffer.Get...`.
+Кроме того, у типа `Buffer` есть дополнительные методы `Buffer.Get*`.
 Соответствующих методов у очередей — нет (`ToDo` возможно, в будущем появятся).
 
-Методы `.Get...` создают новый объект типа записи, массива или выделяют область неуправляемой памяти,
+Методы `.Get*` создают новый объект типа записи, массива или выделяют область неуправляемой памяти,
 читают в полученный объект содержимое буфера и возвращают этот объект.
 Они также используют неявную очередь (для чтения буфера).
 

Packing/Spec/CL ABC/2#Очередь [команд] (CommandQueue)/4#Вложенные очереди/.md

@@ -30,9 +30,9 @@ begin
   
 end.
 ```
-Все очереди-параметры начинают выполнятся сразу при вызове метода `Context.BeginInvoke`, не ожидая других очередей.
+Все вложенные очереди начинают выполнятся сразу при вызове метода `Context.BeginInvoke`, не ожидая других очередей.
 
-Обычно очереди-параметры используются при вызове kernel'а,
+Обычно вложенные очереди используются при вызове kernel'а,
 когда надо записать что-то в буфер прямо перед вызовом kernel'а.
 
 

Packing/Spec/CL ABC/3#Буфер (Buffer)/.md

@@ -18,10 +18,10 @@
 
 Если метод `Buffer.Init` не был вызван до первой операции чтения/записи - он будет вызван автоматически.
 В таком случае в качестве контекста в котором выделяется память берётся тот,
-для которого вызвали `.BeginInvoke`, который запустил команду чтения/записи буфера.
+на котором вызвали `.BeginInvoke`, который запустил команду чтения/записи буфера.
 
 Память на GPU можно моментально освободить, вызвав метод `Buffer.Dispose`.
-Но если снова использовать буфер, у которого освободили память - память опять выделится.
+Но если снова использовать буфер, у которого освободили память - память заново выделится.
 
 Если сборщик мусора удаляет объект типа `Buffer` - `.Dispose` вызывается автоматически.
 

Packing/Spec/CL ABC/5#Kernel/.md

@@ -30,17 +30,19 @@ begin
   
   var A := new Buffer( 10 * sizeof(integer) ); // буфер на 10 чисел типа "integer"
   
-  // 'TEST' - имя подпрограммы-кёрнела из .cl файла. Регистр важен!
+  // 'TEST' - имя подпрограммы-kernel'а из .cl файла. Регистр важен!
   var kernel := code['TEST'];
   
   kernel.Exec1(10, // используем 10 потоков
     
     A.NewQueue.AddFillValue(1) // заполняем весь буфер единичками, прямо перед выполнением
-    as CommandQueue<Buffer> //ToDo нужно только из за issue компилятора #1981, иначе получаем странную ошибку. Когда исправят - можно будет убрать
+    //ToDo нужно только из за issue компилятора #1981
+    as CommandQueue<Buffer>
     
   );
   
-  A.GetArray1&<integer>.Println; // читаем весь буфер как одномерный массив с элементами типа "integer" и сразу выводим
+  // читаем весь буфер как одномерный массив с элементами типа "integer" и сразу выводим
+  A.GetArray1&<integer>.Println;
   
 end.
 ```