Most common/liked syntax for in-code documentation (comments)?

Question

I've been coding PHP with Notepad++ for years now, but today I downloaded Eclipse IDE. One of its features is auto-completing certain "syntax-patterns", such as comments. I've seen a lot of different ways to implement comments and documentation into php-files, so now I started wondering, should I follow the syntax Eclipse suggests.

Here's a snap of what I mean:

What do you think?

Martti Laine

Answer 1

it's phpdoc format, a way to auto document your code using comments.

http://www.phpdoc.org/

Answer 2

Eclipse appears to be picking up phpDoc (probably the most common solution for PHP projects and one I'm happily recommend) elements, which are a great way of documenting the various classes, methods, method arguments, etc. as well as providing a means of tracking to-do's, marking functions/methods as deprecated, etc.

Additionally, you can of course generation documentation in HTML, PDF, CHM format, etc. using the phpdoc command line tool

You can find out more (and check out the required syntax) on the phpDoc site.

Answer 3

Eclipse will do it's best to use heredoc/phpdoc comments which can then be compiled into documentation. Try writing a function then putting a /** comment above it and you'll see ecplise automatically adds the function parameters in the comment.

If you have a look at the Java API, that is the kind of documentation that get's compiled from that style of comments.

If you don't think you're ever going to compile your comments into docs then don't feel bound by it and extra comments in code are always useful. However, it is a documentation standard so it's not a bad thing. I only tend to use this style of commenting for things that I know lots of other people will be looking over.

Answer 4

As pointed out by others, using that kind of comments for phpdoc can be very valuable. But I think it is not only about generating documentation, but making it easier for you to write code as well. Some IDEs (at least Netbeans) use phpdoc comments for providing better autocomplete features than otherwise would be available.