Форум программистов, компьютерный форум, киберфорум
PHP для начинающих
Войти
Регистрация
Восстановить пароль
Блоги Сообщество Поиск Заказать работу  
 
Рейтинг 4.73/15: Рейтинг темы: голосов - 15, средняя оценка - 4.73
 Аватар для noname_club
112 / 103 / 12
Регистрация: 01.05.2013
Сообщений: 603

PHPDoc автоматизация заполнения комментариев

23.05.2015, 23:23. Показов 3078. Ответов 4
Метки нет (Все метки)

Студворк — интернет-сервис помощи студентам
Есть статья Wiki
https://ru.wikipedia.org/wiki/PHPDoc

При разработке своих больших проектов, все тонкости которых невозможно держать в голове, ровно как и при доработке чужих проектов, часто приходится подсматривать в ранее написанный код.

Это позволяет точнее представлять себе и возвращаемые, создаваемые объекты и что с ними можно делать. Учитывая, что в PHP нет строгой типизации, потенциально возможны ошибки, когда сравниваются несравниваемые объекты. Например: строка и число, массив и константа. В некоторых случаях PHP даже не выдаёт ошибку при таком сравнении, просто преобразуя типы к одинаковым (если это в принципе возможно). В языках со строгой типизацией этого не произойдёт - программа просто не будет компилироваться.

Для избежания этого и используют PHPDoc и другие подобные технологии.
Это означает что если разрабатываешь действительно большую систему (не быдло код) на PHP,

то в силу отсутствия типизации нужно ОБЯЗАТЕЛЬНО помечать каждый метода класса, каждое свойство КАКОГО ОНИ ТИПА.

Привожу пример такого кода на примере

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<?php
class GeSHi {
    /**#@+
     * @access private
     */
    /**
     * The source code to highlight
     * @var string
     */
    var $source = '';
 
    /**
     * The language to use when highlighting
     * @var string
     */
    var $language = '';
 
    /**
     * The data for the language used
     * @var array
     */
    var $language_data = array();
    
    /**
     * Creates a new GeSHi object, with source and language
     *
     * @param string The source code to highlight
     * @param string The language to highlight the source with
     * @param string The path to the language file directory. <b>This
     *               is deprecated!</b> I've backported the auto path
     *               detection from the 1.1.X dev branch, so now it
     *               should be automatically set correctly. If you have
     *               renamed the language directory however, you will
     *               still need to set the path using this parameter or
     *               {@link GeSHi->set_language_path()}
     * @since 1.0.0
     */
    function GeSHi($source = '', $language = '', $path = '') {
        if (!empty($source)) {
            $this->set_source($source);
        }
        if (!empty($language)) {
            $this->set_language($language);
        }
        $this->set_language_path($path);
    }

То есть нужно ОБЯЗАТЕЛЬНО писать эти простыни комментариев вместо того чтобы реально заниматься любимым программированием

Все это оправдано в будущем, но написание комментариев еще не написанной системы версии v0.0.0 просто невыносимо утомительно.

ВОПРОС: ответ на который будет полезен многим.

---------------

Как это можно автоматизировать? Может это уже автоматизировано. Может есть сниппеты и прочее?
0
cpp_developer
Эксперт
20123 / 5690 / 1417
Регистрация: 09.04.2010
Сообщений: 22,546
Блог
23.05.2015, 23:23
Ответы с готовыми решениями:

Автоматизация для добавления товаров, чтобы после заполнения марки, модели остальное описание парсилось с другого сайта
Карточка товара состоит из марки, модели, описания, картинок, тайтла, дескриптора и разных характеристик товара. В ней заполняются поля...

Автоматизация заполнения
Есть вот такая таблица: Данные в нее заполняются с учетом другого документа (т.е. расписания). Например: у группы 1з-1 в этот день...

Автоматизация заполнения word
Здравствуйте! Такая проблема: имеется расчетная программа, написанная на фортране, производящая достаточно сложные вычисления. С другой...

4
Эксперт PHP
5755 / 4134 / 1508
Регистрация: 06.01.2011
Сообщений: 11,276
24.05.2015, 06:18
Цитата Сообщение от noname_club Посмотреть сообщение
просто невыносимо утомительно
Никто не говорил, что будет легко. Комментарии к коду по-любому - писать Вам. А чтобы каждый раз не прописывать звёздочки, @var, @param и подобное - используйте нормальную IDE. Она при открытии комментария сама будет дополнять его, чтобы Вам не приходилось самому выполнять однотипную работу.
0
 Аватар для noname_club
112 / 103 / 12
Регистрация: 01.05.2013
Сообщений: 603
07.06.2015, 14:57  [ТС]
Залью сюда пример оформления кода классов, скопированный из исходников CodeIgniter

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
<?php
 
### болле полный мануал по оформлению исходного кода классов можно посмотреть на 
### http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html
 
##### Оформление локальных define 
 
/**
 * Описание параметра define
 *
 * @var string
 */
define('CI_VERSION', '3.0.0');
 
##### Оформление локальной фукнции
 
/**
 * Get "now" time
 *
 * Returns time() based on the timezone parameter or on the
 * "time_reference" setting
 *
 * @param   string
 * @return  int
 */
function now($timezone = NULL) { 
    // bla / bla 
}
 
##### Оформление класса 
 
/**
 * CodeIgniter
 *
 * (описание класса) An open source application development framework for PHP 5.1.6 or newer
 *
 * @package     CodeIgniter
 * @author      ExpressionEngine Dev Team
 * @copyright   Copyright (c) 2008 - 2014, EllisLab, Inc.
 * @license     http://codeigniter.com/user_guide/license.html
 * @link        http://codeigniter.com
 * @since       Version 1.0
 * @filesource
 */
 
class ClassName {
    
    /**
     * Назначение переменной
     *
     * @var тип переменной (array,string,int,Class)
     */
    var $marker = array();
 
    /**
     * Назначение метода, ниже показан образец заполнения описания функции
     *
     * @param   string  $file           Configuration file name
     * @param   bool    $use_sections       Whether configuration values should be loaded into their own section
     * @param   bool    $fail_gracefully    Whether to just return FALSE or display an error message
     * @return  bool    TRUE if the file was loaded correctly or FALSE on failure
     */
     
    public function load($file = '', $use_sections = FALSE, $fail_gracefully = FALSE) {
        // bla bla
    }
    
    /**
     * Описание метода возврающего несколько типов данных
     *
     * @param   string  $item   Config item name
     * @param   string  $index  Index name
     * @return  string|null The configuration item or NULL if the item doesn't exist
     */
    public function item($item, $index = '') {
        // bla bla
    }
    
    /**
     * Описание метода используещего массив строк с качестве входного параметра 
     *
     * Returns base_url . index_page [. uri_string]
     *
     * @uses    CI_Config::_uri_string()
     *
     * @param   string|string[] $uri    URI string or an array of segments
     * @param   string  $protocol
     * @return  string
     */
    public function site_url($uri = '', $protocol = NULL) {
        // bla / bla
    }
}
Вложения
Тип файла: zip PHPClassCommentExample.zip (1.4 Кб, 1 просмотров)
0
 Аватар для noname_club
112 / 103 / 12
Регистрация: 01.05.2013
Сообщений: 603
07.06.2015, 15:29  [ТС]
Для автоматизации можно использовать 3 универсальнных сниппета (шаблона кода)

Создать из можно вот так:

IDE Netbeans

Сервис -> Параметры -> Редактор -> Шаблоны кода -> PHP

Tools -> Options -> Editor -> Code Templates-> PHP



Создаем сниппет через [Новый] указываем ключевое слово по которому он будет срабыватывать
И заполняем сниппет
Также метод ракрытия должен быть установлен на [ВВОД] или [Enter], так он будет раскрываться по нажатию Enter

Выкладываю свой список сниппетов для phpDoc



PHPDocSnippets.zip
0
 Аватар для noname_club
112 / 103 / 12
Регистрация: 01.05.2013
Сообщений: 603
29.07.2015, 17:44  [ТС]
Добавлю ссылку про то что PHP все таки позволяет жестко задавать типы данных
Такая возможность доступна еще с PHP5

http://php.net/manual/ru/langu... inting.php

Явное указание типов в некоторых случаях позволяет не писать комментарий к функции, достаточно указать типы передаваемых параметров.

PHP
1
2
3
4
5
class A {  function foo(B $b) { var_dump($b);  } }
$a = new A();
$a->foo(null); // Catchable fatal error: Argument 1 passed to A::foo() must be an instance of B
$b = null;
$a->foo($b); // Catchable fatal error: Argument 1 passed to A::foo() must be an instance of B
Однако есть ограничения на скалярные типы
0
Надоела реклама? Зарегистрируйтесь и она исчезнет полностью.
raxper
Эксперт
30234 / 6612 / 1498
Регистрация: 28.12.2010
Сообщений: 21,154
Блог
29.07.2015, 17:44
Помогаю со студенческими работами здесь

Автоматизация заполнения форм
Здравствуйте! Подскажите, пожалуйста, есть ли возможность средствами C# взаимодействовать со сторонними программами? А именно,...

Автоматизация заполнения документов
Всем привет! Нужно разработать программу по автоматизации заполнения документов.Вопрос состоит в том как реализовать, чтобы после...

Автоматизация заполнения форм из БД
Доброго времени суток) Для диплома нужно сделать с помощью БД автоматическое заполнение шаблона формы отчётности на фирме, т.е работники...

Автоматизация заполнения форм
Доброе время, такой вопрос. Возможно ли в С# создать автоматизацию для заполнения веб формы к примеру для GooglePlay, создания нового...

Автоматизация заполнения нескольких полей
Подскажите, кто знает... Есть страница (Forma), где данные со страницы (Dani) организованы в виде списков, можно ли сделать так, что при...


Искать еще темы с ответами

Или воспользуйтесь поиском по форуму:
5
Ответ Создать тему
Новые блоги и статьи
Оттенки серого
Argus19 18.03.2026
Оттенки серого Нашёл в интернете 3 прекрасных модуля: Модуль класса открытия диалога открытия/ сохранения файла на Win32 API; Модуль класса быстрого перекодирования цветного изображения в оттенки. . .
SDL3 для Desktop (MinGW): Рисуем цветные прямоугольники с помощью рисовальщика SDL3 на Си и C++
8Observer8 17.03.2026
Содержание блога Финальные проекты на Си и на C++: finish-rectangles-sdl3-c. zip finish-rectangles-sdl3-cpp. zip
Символические и жёсткие ссылки в Linux.
algri14 15.03.2026
Существует два типа ссылок — символические и жёсткие. Ссылка в Linux — это запись в каталоге, которая может указывать либо на inode «файла-ИСТОЧНИКА», тогда это будет «жёсткая ссылка» (hard link),. . .
[Owen Logic] Поддержание уровня воды в резервуаре количеством включённых насосов: моделирование и выбор регулятора
ФедосеевПавел 14.03.2026
Поддержание уровня воды в резервуаре количеством включённых насосов: моделирование и выбор регулятора ВВЕДЕНИЕ Выполняя задание на управление насосной группой заполнения резервуара,. . .
делаю науч статью по влиянию грибов на сукцессию
anaschu 13.03.2026
прикрепляю статью
SDL3 для Desktop (MinGW): Создаём пустое окно с нуля для 2D-графики на SDL3, Си и C++
8Observer8 10.03.2026
Содержание блога Финальные проекты на Си и на C++: hello-sdl3-c. zip hello-sdl3-cpp. zip Результат:
Установка CMake и MinGW 13.1 для сборки С и C++ приложений из консоли и из Qt Creator в EXE
8Observer8 10.03.2026
Содержание блога MinGW - это коллекция инструментов для сборки приложений в EXE. CMake - это система сборки приложений. Здесь описаны базовые шаги для старта программирования с помощью CMake и. . .
Как дизайн сайта влияет на конверсию: 7 решений, которые реально повышают заявки
Neotwalker 08.03.2026
Многие до сих пор воспринимают дизайн сайта как “красивую оболочку”. На практике всё иначе: дизайн напрямую влияет на то, оставит человек заявку или уйдёт через несколько секунд. Даже если у вас. . .
КиберФорум - форум программистов, компьютерный форум, программирование
Powered by vBulletin
Copyright ©2000 - 2026, CyberForum.ru