Merge pull request #31 from gromdron/review-1

Grand Review

docs/00_С_чего_начать.md

@@ -1,17 +1,17 @@
 # Введение
 
-Битрикс24 это сложный продукт с богатым наследием, окутанный мифами и тайнами. Можно любить Битрикс24, можно нендавидеть, но если вам приходиться разбираться с ним то это точно для вас. В этой книге мы будем рассматривать коробочную версию Битрикс24 и хотя некоторые аспекты будут симметричны для облачной версии, нашим фокусом будет именно на коробочной версии. Понимание процессов происходящих внутри продукта поможет сократить значительное время на исследование их самостоятельным путем.
+Битрикс24 это сложный продукт с богатым наследием, окутанный мифами и тайнами. Можно любить Битрикс24, можно ненавидеть, но если вам приходиться разбираться с ним то это точно для вас. В этой книге мы будем рассматривать коробочную версию Битрикс24 и хотя некоторые аспекты будут симметричны для облачной версии, нашим фокусом будет именно коробочная версия. Понимание процессов происходящих внутри продукта поможет сократить значительное время на исследование их самостоятельным путем.
 
-Работа над книгой мы держим в фокусе следующие цели:
+Работа над книгой мы ставим перед собой следующие цели:
 
 * Систематизация знаний в области API Битрикс24.
 * Упрощение изучения платформы для новых разработчиков
 
 # С чего начать изучение Битрикс24?
 
-Прежде всего рекомендуется начать пользоваться продуктом, потому что без знания продукта нельзя разрабатывать качественные решения под него. Продукт имеет свою философию и фокус-группу и понимание их в свою очередь дает хороший старт для последующих разработок - вы не просто будете понимать как вашу задачу решает продукт, но и как не следует ее решать, а обычно это узнать можно только на практике.
+Прежде всего рекомендуется начать пользоваться продуктом, потому что без знания продукта нельзя разрабатывать качественные решения под него. Продукт имеет свою философию и ее понимание в свою очередь дает хороший старт для последующих разработок - вы не просто будете понимать как вашу задачу решает продукт, но и как не следует ее решать.
 
-Прежде чем читать этот технический текст, настоятельно рекомендуется ознакомиться с следующими источниками:
+Прежде чем читать этот технический текст, настоятельно рекомендуется ознакомиться со следующими источниками:
 
 * [Поддержка24](https://helpdesk.bitrix24.ru/)
 * [Администратор сервиса Битрикс24 (коробочная версия)](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=48)
@@ -20,10 +20,10 @@
 
 Некоторые разделы данного руководства могут частично или полностью повторять уроки и/или статьи в перечисленных ранее источниках, это не воровство или присваивание чужого интеллектуального труда, а необходимая мера для систематизации знаний в одном месте.
 
-Для понимания значительной части информации потребуются знания только языка программирования PHP, однако для понимания некоторых разделов потребуются дополнительные знания. Мы считаем что минимально ориентироваться стоит на следующе технологии:
+Для понимания значительной части информации потребуются знания языка программирования PHP, однако для понимания некоторых разделов потребуются дополнительные знания. Мы считаем что минимально ориентироваться стоит на следующе технологии:
 
-* Знать PHP 7.4, 8.0, 8.1 и их различия в части обратной совместимости
+* Знать PHP 7.4, 8.0 - 8.2 и их различия в части обратной совместимости
 * JavaScript - в продукте используются разные технологии включая JS, ES6, TypeScript
 * SQL (основная субд - MySQL / Percona Server / MariaDB)
-* Linux (базовое владение в том числе комманды cd, ls, chmod, chown, vi/vim/nano, cat, tail, grep, rm и др.)
-* Общие знания по работе протоколов HTTP, DNS, SSL, SMTP, IMAP/POP3
+* Linux (базовое владение, в том числе команды: `cd`, `ls`, `chmod`, `chown`, `vi`/`vim`/`nano`, `cat`, `tail`, `grep`, `rm` и др.)
+* Общие знания по работе протоколов HTTP, DNS, SMTP, IMAP/POP3

docs/01_Документация/00_Справочник.md

@@ -1,6 +1,6 @@
 # Вступление
 
-Перед тем как погружаться в изучение Битрикс24 необходимо иметь хотя бы поверхностные знания о продукте, а лучшее место где можно подчерпнуть эти знания является документация.
+Перед тем как погружаться в изучение Битрикс24 необходимо иметь хотя бы поверхностные знания о продукте, а лучшее место где можно подчеркнуть эти знания является документация.
 
 На этой странице мы пытаемся собрать ссылки на информационные ресурсы, которые так или иначе связаны с продуктом.
 

docs/01_Документация/01_Сам_себе_источник.md

@@ -8,9 +8,9 @@
 
 >Если для искомого механизма существует REST метод, то его можно найти и посмотреть как он реализован. 
 
-Модуль REST является скорее техническим модулем нежели самостоятельным. Его архитектурная идея состоит в том, чтобы помочь другим модулям предоставив механизм для описания REST методов, а так же предоставить возможность использовать внешними системами это API. Таким образом найдя все подписки на этот модуль, можно найти все методы которые доступны через REST. 
+Модуль REST является скорее техническим модулем, нежели самостоятельным. Его архитектурная идея состоит в том, чтобы помочь другим модулям предоставив механизм для описания REST методов, а так же предоставить возможность использовать внешними системами это API. Таким образом найдя все подписки на этот модуль, можно найти все методы которые доступны через REST. 
 
-Интересующее нас событие onRestServiceBuildDescription модуля rest. Именно на него подписываются существующие модули или произвольный php-код и дополняют существующие методы (или переопределяют). Для того чтобы определить все классы которые предоставляют rest-методы можно выполнить фрагмент кода в Командной PHP-строке:
+Интересующее нас событие onRestServiceBuildDescription модуля rest. Именно на него подписываются существующие модули или произвольный php-код и дополняют существующие методы (или переопределяют). Для того чтобы определить все классы, которые предоставляют rest-методы можно выполнить фрагмент кода в Командной PHP-строке:
 
 ```php
 var_dump(\GetModuleEvents('rest', 'onRestServiceBuildDescription')); 
@@ -26,26 +26,26 @@ var_dump(\GetModuleEvents('rest', 'onRestServiceBuildDescription'));
 Таким образом, в случае если для определенной сущности выбрано название, то оно будет фигурировать во всех связанных с ней областях. Так например, для сделки выбрано DEAL, тогда все классы так или иначе будут связаны со сделкой.
 
 Пример:
-* Класс CCrmDeal
-* Класс \Bitrix\Crm\DealTable
-* Класс \Bitrix\Crm\Recycling\DealBinder
-* Константа SONET_CRM_DEAL_ENTITY
+* Класс `CCrmDeal`
+* Класс `\Bitrix\Crm\DealTable`
+* Класс `\Bitrix\Crm\Recycling\DealBinder`
+* Константа `SONET_CRM_DEAL_ENTITY`
 
 Этой информации достаточно для начала поиска, в то время как именование классов будет рассмотрено отдельно в соответствующем разделе.
 
 ## Исследование через css-класс или вспомогательные зацепки
 
 Иногда может потребоваться найти вывод какого-нибудь специального фрагмента, например языковой фразы или css-класса и такой поиск может существенно затянуться, ведь они могут быть разбросаны по системе в сотнях огромных файлах.
 
-Для этого на выручку приходят коммандные утилиты linux, такие как grep. Подробнее с коммандой можно разобраться по [доступным статьям в сети интернет](https://losst.ru/gerp-poisk-vnutri-fajlov-v-linux), мы же воспользуемся краткой выжимкой.
+Для этого на выручку приходят командные утилиты linux, например `grep`. Подробнее с командой можно разобраться по [доступным статьям в сети интернет](https://losst.ru/gerp-poisk-vnutri-fajlov-v-linux), мы же воспользуемся краткой выжимкой.
 
 ```bash
 grep -ril 'something' ./some_path
 ```
 
-Комманда выполняет рекурсивный (``r``) регистронезависимый (``i``) поиск something в директории ``./some_path`` выводя исключительно файлы (``l``). 
+Команда выполняет рекурсивный (``r``) регистро-независимый (``i``) поиск something в директории ``./some_path`` выводя исключительно файлы (``l``). 
 
-Например, если выполнить нижеописанную комманду в директории ``/home/bitrix/www/bitrix/modules/crm/lib`` 
+Например, если выполнить нижеописанную команду в директории ``/home/bitrix/www/bitrix/modules/crm/lib`` 
 
 ```bash
 grep -ril 'DEAL' ./
@@ -68,7 +68,7 @@ grep -ril 'DEAL' ./
 ./tracking/analytics/dataprovider.php
 ```
 
-Иногда для исследования необходимо отследить не только конкретный фрагмент но и его окружение, тогда полезным будет другой модификатор комманды: ``n``.
+Иногда для исследования необходимо отследить не только конкретный фрагмент, но и его окружение, тогда полезным будет другой модификатор команды: ``n``.
 
 Например, мы хотим найти то же слово, но нас так же интересует контекст (номер стройки и ее содержимое). Выполняем измененную команду в той же директории:  
 ```bash
@@ -95,14 +95,14 @@ grep -rin 'DEAL' ./
 ./ads/adsaudience.php:79:                                       $entityDb = \CCrmDeal::getListEx(array(), $subFilter);
 ```
 
-Помните, что рекурсивый вызов grep может занять достаточно продолжительное время, поэтому рекомендуется ограничивать область поиска локализуя его перед тем как выполнить комманду.
+Помните, что рекурсивный вызов grep может занять достаточно продолжительное время, поэтому рекомендуется ограничивать область поиска локализуя его перед тем как выполнить команду.
 
 ## Исследование JS-событий
 
 Достаточно часто возникает ситуация когда нужно повлиять на текущую страницу, например убрать какие-либо элементы или изменить их поведение.
-Зачастую неопытные разработчики пытаются применить timeout-механизм, который может сыграть с ним злую шутку и на пользовательском ПК не сработать.Наиболе правильным вариантов в данном случае будет использование событий страницы. 
+Зачастую неопытные разработчики пытаются применить timeout-механизм, который может сыграть с ним злую шутку и на пользовательском ПК не сработать. Наиболее правильным вариантом в данном случае будет использование событий страницы. 
 
-В отличии от php-событий системы события публичной части не описываются и приходится искать их по всей системе, а советы которые предлагают разработчики уже не работают (привет новому коду из ES6). Как же тогда искать все вызовы?
+В отличие от php-событий системы события публичной части не описываются и приходится искать их по всей системе, а советы которые предлагают разработчики уже не работают (привет новому коду из ES6). Как же тогда искать все вызовы?
 
 Помощь приходит откуда не ждали: в браузере Mozilla Firefox присутствуют [механизмы отладки в браузере](https://developer.mozilla.org/en-US/docs/Tools/Debugger). Нас интересует логгирование в браузере [Set a logpoint](https://developer.mozilla.org/en-US/docs/Tools/Debugger/Set_a_logpoint).