Правильный синтаксис дляоризит в phpDocumentor
Какой правильный синтаксис для @inheritDoc в phpDocumentor, если я просто хочу наследовать всю документацию от родительского? Может быть, более одного синтаксиса является правильным?
@inheritDoc{@inheritDoc}@inheritdoc{@inheritdoc}
Документация довольно расплывчатая, я думаю. Кажется, что PhpStorm поддерживает их все, но, возможно, у меня возникнут проблемы при создании документов с некоторым синтаксисом?
2 ответа
Дочерний элемент должен автоматически наследовать почти все от своего родительского docblock без использования этого тега. В противном случае все ваши методы реализации должны были бы снова и снова документироваться, ничего не получая от оригинальной документации интерфейса.
Проще говоря, унаследованный элемент без докблока должен автоматически наследовать все от докблока его родителя.
@inheritdoc Единственная цель тега состоит в том, чтобы помочь вам импортировать одну вещь из родительского docblock - Длинное описание этого родителя. Единственная причина, по которой ребенок не должен иметь это в наличии, - это то, что ребенок пошел вперед и имел собственный док-блок. Теперь дочерний элемент должен все еще наследовать почти все от своего родительского docblock без необходимости дублировать его... кроме длинного описания родителя. Если дочерний докблок по какой-то причине решил иметь свой собственный докоблок, и вы все еще хотите унаследовать длинное описание родителя, то куда вы помещаете @inheritdoc в дочернем docblock определяет, где появляется это родительское длинное описание. Таким образом, дочерний элемент может иметь свое собственное краткое описание и длинное описание, а также включать в себя длинное описание своего родителя в указанном месте по отношению к дочернему подробному описанию. Это единственная причина, по которой этот тег когда-либо родился:-)
Что касается автозаполнения IDE, я не могу сказать, что я видел согласованное поведение в IDE, когда дело доходит до этого тега. Кроме того, я видел проекты, в которых делается предположение, что этот тег является причиной того, что наследуется информация от родительских docblocks.
Я ничего не знаю о поддержке IDE, но в документации написано, что {@inheritDoc},