Наиболее распространенный / понравившийся синтаксис для документации в коде (комментарии)?

Question

Я кодирую PHP с Notepad ++ уже много лет, но сегодня я скачал Eclipse IDE. Одна из его функций - автозаполнение определенных «синтаксических паттернов», таких как комментарии. Я видел много разных способов реализации комментариев и документации в php-файлы, так что теперь я начал задаваться вопросом, должен ли я следовать синтаксису, предложенному Eclipse.

Вот несколько слов о том, что я имею в виду:

Что ты думаешь?

Марти Лайн

Answer 1

это формат phpdoc, способ автоматического документирования вашего кода с помощью комментариев.

http://www.phpdoc.org/

Answer 2

Как отмечают другие, использование такого рода комментариев для phpdoc может быть очень полезным.Но я думаю, что речь идет не только о создании документации, но и о том, как вам будет проще писать код.Некоторые IDE (по крайней мере, NetBeans) используют комментарии phpdoc для обеспечения лучших функций автозаполнения, чем было бы доступно в противном случае.

Answer 3

Eclipse сделает все возможное, чтобы использовать комментарии heredoc / phpdoc, которые затем могут быть скомпилированы в документацию. Попробуйте написать функцию, а затем поместить комментарий / ** над ней, и вы увидите, что ecplise автоматически добавляет параметры функции в комментарий.

Если вы посмотрите на Java API, это документация, которая компилируется из этого стиля комментариев.

Если вы не думаете, что когда-нибудь соберете свои комментарии в документы, не стесняйтесь этого, и дополнительные комментарии в коде всегда полезны. Тем не менее, это стандарт документации, так что это неплохо. Я склонен использовать этот стиль комментирования только для тех вещей, которые, как я знаю, многие другие люди будут просматривать.

Answer 4

Eclipse, похоже, собирает phpDoc (вероятно, наиболее распространенное решение для проектов PHP, и я с удовольствием рекомендую его), которые являются отличным способом документирования различных классов, методов, аргументов методов.и т. д., а также средства отслеживания дел, маркировки функций / методов как устаревших и т. д.

Кроме того, вы, конечно, можете создавать документацию в формате HTML, PDF, CHM и т. д., используяИнструмент командной строки phpdoc

Вы можете узнать больше (и проверить необходимый синтаксис) на сайте phpDoc .