Как Вы документируете свои функции PHP и встроенные классы? [закрытый]
Предпочитают состав по наследованию, поскольку это более покорно / легкий изменить позже, но не использует подход сочинения всегда. С составом, легко изменить поведение на лету с Внедрением зависимости / Методы set. Наследование более твердо, поскольку большинство языков не позволяет Вам происходить больше чем из одного типа. Таким образом, гусь более или менее приготовлен, как только Вы происходите из TypeA.
Мое испытание на кислотность для вышеупомянутого:
- TypeB хочет представить полный интерфейс (все открытые методы не меньше) TypeA, таким образом, что TypeB может использоваться, где TypeA ожидается? Указывает Наследование .
, например, биплан Cessna представит полный интерфейс самолета, если не больше. Таким образом, это заставляет его соответствовать для получения из Самолета.
- TypeB хочет только часть/часть поведения, представленного TypeA? Указывает на потребность в [1 110] Состав.
, например, Птица, возможно, нуждается только в поведении мухи Самолета. В этом случае имеет смысл извлекать его как интерфейс / класс / оба и делать его членом обоих классов.
Обновление: Просто возвратился к моему ответу, и это кажется теперь, когда это неполно без определенного упоминания о Barbara Liskov принцип замены Лисков как тест для, 'Я должен наследоваться этому типу?'
4 ответа
PHPDoc, like what you've posted, is a widely accepted form of PHP documentation.
You can use Doxygen to auto-generate the docs.
Edit: In terms of generating in-line documentation in your code, I have never come across a tool that will go back and do this externally for a project. It's generally left in the realm of the IDE to generate a template while you code.
Eclipse actually does a decent job of this (it's one of the few things I like about Eclipse) and I believe Netbeans does as well. Any major IDE will likely have functionality to assist with this type of template generation.
Обычно вы пишете комментарии к документу сами, хотя я полагаю, что некоторые IDE могут создать для вас шаблон.
Я действительно написал программу, которая может отслеживать запущенную программу и определять типы параметров и напишите их как комментарии к документу . Это немного глючит, но вроде работает.
Не знаю, что вы кодируете, но у меня есть несколько фрагментов (я использую Textmate), которые я просто добавляю, когда работаю). Я обнаружил, что это дает наилучшие результаты, так как вместо этого я заполняю детали доверять системе делать это за меня.
Вначале это больше работы, но, похоже, она того стоит в долгосрочной перспективе
Хотя я не использовал его полностью, Doxygen выглядит многообещающим для этой задачи.
Если вы знакомы с инструментом JavaDoc для Java, он очень похож на который. Вы используете стиль Doxygen, а затем запускаете инструмент над исходными файлами для создания документации.