phpdoc preview

phpdoc.md

@@ -1,6 +1,6 @@
 # PHPDoc
 
-**PHPDoc** - система документирования **PHP** кода, основанная на **Javadoc**. Суть системы заключается в том, что к коду пишутся комментарии специального формата перед теми или иными сущностями (функциями, классами и т. д.). В дальнейшем эти
+**PHPDoc** - система документирования **PHP** кода, основанная на **Javadoc**. Суть системы заключается в том, что к коду пишутся комментарии специального формата перед теми или иными сущностями (функциями, классами, методами, свойствами и т. д.). В дальнейшем эти
 комментарии парсятся **IDE** (для подсказок в автодополнении) или специальными утилитами (**PHPDocumentor**) для генерации документации по коду.
 
 ## Синтаксис
@@ -13,4 +13,168 @@
  */
 ```
 
-Как видите, это обычный *многострочный*
+Как видите, это обычный *многострочный* комментарий, у которого *две* звездочки в начале комментария, в отличие от обычных комментариев.
+
+### Директивы (тэги)
+
+Директива (тэг) - одно поле, которое несет определенную информацию о сущности кода. Начинаются с собаки `@`. Например
+- `@param` - параметр функции/метода
+- `@return` - тип и описание возвращаемого значения метода/функции.
+- `@var` - тип и описание переменной/свойства объекта
+
+### Общие директивы файла 
+
+Ниже приведены директивы, которые *обычно* указываются в начале файла и относятся ко всему файлу с кодом
+
+#### `@author`
+
+Имя автора кода:
+
+```php
+/**
+ *  @author Name Surname 
+ *  @author Name Surname <email@example.com>
+ */
+```
+
+#### `@copyright`
+
+```php
+/**
+ *  @copyright 1980-20100500 The Super Team
+ */
+```
+
+#### `@license`
+
+```php
+/**
+ *  @license MIT
+ *  или
+ *  @license https://opensource.org/licenses/MIT  
+ */
+```
+
+#### `@package`
+
+Обычно применяются для документирования и/или разделения кода на логические элементы. Зачастую совпадает (хотя вовсе не обязательно) с тем или иным `namespace`
+
+```php
+/**
+ * @package yii\base\Model
+ */
+```
+
+#### `@see`
+
+Ссылка на дополнительный материал. Может быть внешней ссылкой или ссылкой на другой блок **PHPDoc**
+
+```php
+/**
+ *  @see http://google.com
+ *  @see http://php.net
+ *  @see ContactForm::rules
+ */
+```
+
+#### `@version`
+
+Версия. Может быть указана литерально, или же взята из системы контроля версий
+
+```php
+/**
+ * @version 0.0.1 Pre-alpha
+ * @version GIT: $Id$
+ */
+```
+
+Для задания версии в **git** надо поколдовать с `git describe`
+
+### Тэги классов
+
+Ниже показаны тэги, которые относятся к *классам*
+
+#### `@method`
+
+Несмотря на очевидное название, это не то, что вы подумали. Данный тэг используется для возможных "фейковых" методов, которые работают благодаря магическому методу `__call`. Для обычных методов специального тэга нет, так как они определяются благодаря ключевому
+слову "function"
+
+```php
+
+/**
+ *  @method void reboot()
+ *  @method bool shutdown()
+ */
+class MagicCallableClass {
+    function __call($name, $arguments){
+        if ($name === 'reboot'){
+            echo "рыбут";
+        }
+        if ($name === 'shutdown'){
+            echo "выкл";
+            return true;
+        }
+    }
+}
+```
+
+В примере выше нет отдельных методов `reboot` и `shutdown`, однако есть логика в `__call`, которая обеспечивает их работу
+
+#### `@property`, `@property-read`, `@property-write`
+
+Описания свойств, созданных с помощью `__get` и `__set`, аналогично @method
+
+### Тэги сущностей классов и объектов
+
+#### `@abstract`
+
+Абстрактные методы и свойства
+
+#### `@access`
+
+Тип доступа: `private`, `public` или `protected`
+
+#### `@final`
+
+ООП final
+
+### Функции и методы
+
+**PHPDoc** указываются непосредственно перед функцией или методом
+
+#### `@param`
+
+Самый часто употребляемый тэг:
+
+```php
+/**
+ *  @param Тип Имя Описание 
+ */
+
+```
+
+```php
+/**
+ *  @param int $afterSeconds Delay before reboot
+ */
+function reboot($afterSeconds){
+
+}
+```
+
+#### `@return`
+
+Очевидно, тип и описание возвращаемого значения функции
+
+```php
+/**
+ *  @param double $value Value to calculate square root of it
+ *  @return double|NAN Square root or NAN if $value less than zero
+ */
+
+function sqrt($value){
+    ...
+}
+```
+
+