What is Reddit's opinion of phpDocumentor 2?

From 3.5 billion Reddit comments

Some options:

• Doxygen
• PHPDoctor
• phpDocumentor

In the past I have used phpDocumentor but it hasn't been updated in years, and is a pain to work with.

I've heard good things about Doxygen, but have also heard it can be a bit complex to work with because it also supports other languages.

Absolutely, yes. Docblocks are useful primarily for two reasons:

• IDE integration for features which are ambiguous or impossible based on the language syntax and context itself, and
• Automated generation of documentation from the source code (using e.g. phpDocumentor).

That doesn't mean you can't write quality code without docblocking all the things, by any means, but it's always nicer to have it than not.

> my preference in all languages and projects is for the PHPdoc style unless a client requests otherwise.

Those aren't idiomatic phpDoc comments, though. As explained here, you shouldn't be using a long line of ---'s as a demarcation point in the comment -- you should either use a blank line, or use a period on the first line.

I think it's also a little nuanced to insert a blank line between the docblock and the code it's commenting, don't think I've ever seen that before (and it eats up a full line).

This is also a little unorthodox (not saying it's wrong, just that I rarely see it):

/* Month can come in as string. If string, get the number of the * month from the indexes in months. */ month = months.indexOf(month);

The rule-of-thumb I believe, is that if you're going to use /* and */, they should each be on their own line without anything else. Otherwise, if you don't want to eat up those lines, then I'd just use // comments.

Lastly, for something like this:

if (year == dates.year && month == dates.month) { // If month and year are current, use current day of month. days.start = dates.day; }

I'd much rather the comment be on the line preceding the code block, instead of inside of it. Reason being, the comment describes the entire block, but you have it embedded so that it looks like it's only describing the inner block, which isn't the case.

To add to #1, Follow phpdoc

To add to #2, I would say PSR 2 is a good way to go, and it can be autoformatted using php-cs-fixer build by the same people who make Symfony.

To add to #4, this would be a major turn away to me, if I were an employer, since it is also very inefficient and hides some issues. There are occasions in PHP where it is necessary (since a built-in function throws warnings instead of exceptions etc), but these are few and far between.

From http://www.php.net/manual/en/language.basic-syntax.comments.php.

"Comments in PHP can be used for several purposes, a very interesting one being that you can generate API documentation directly from them by using PHPDocumentor (http://www.phpdoc.org/).

Therefore, one has to use a JavaDoc-like comment syntax (conforms to the DocBook DTD), example:"

Therefore, it's to simplify documentation and keep you from having to re-write comments into documentation.

Check into phpDocumentor. It's a way to auto-document via formatting your comments a specific way. I hear IDE's can parse it for inteli-sense stuff too.

/** * example of basic @param usage * @param bool $baz * @return mixed */ function function1($baz) { if ($baz) { $a = 5; } else { $a = array(1,4); } return $a; }

Here's a better example: Sample #3 on manual.phpdoc.org

I would recommend both using PHPDoc, which provides precise documentation for the API of your code, but also prose documentation in the form of a wiki or other easily editable system. This prose documentation shows examples, explains why things happen and how different parts interact. You certainly can write your prose inside of DocBlock comments, I've just found it extremely cumbersome. I've found that making it really easy to edit the documentation helps to make it easier to keep it up to date.

The most popular documentation generator for PHPDoc is probably PhpDocumentor. I personally hate the PhpDocumentor codebase, having done quite a bit of work to make it create more usable output. Ironically I've found the documentation rather poor. :-\ There is also DocBlox, although I have never used it.

If you want an example of what I am talking about, you can check out the Flourish documentation. Each class name links to the prose documentation, which I refer to as Class Documentation. The API Reference is the output of PhpDocumentor.

Another recommendation I have for documentation is to try and include as much cross-linking between types of documentation as possible. I keep a class-level navigation block in the same place on each page which allows you to jump from the Class Documenation, API reference or source code to any of the other three. Providing links to the different headings on the page is really helpful too.

Like psy-borg said, the instructions for phpDocumentor are at phpdoc.org

Make sure to have a look at Sami and apigen for alternatives.

I love the idea and would totally use it, but you may be asking for upvotes in the wrong place.

I think you want to get the syntax defined and approved by the 'official' PHP Docblock standard. I'm not sure if their website or Github would be the best place to propose it.

While they are lovely, the Jetbrains guys are really not the right people to be inventing new features for PHP Docblock.

> Why do you need a comment for all this stuff when the code is RIGHT THERE underneath communicating the exact same information.

It's not for human consumption - this is for document generators and IDEs.

+1 for PHPDoc

If you're taking on additional developers if may be a good idea to look at phpUnderControl to enforce coding standards and unit test coverage. It also has PhpDocumentor integration which is a nice bonus.

You are right of course, I didn't think about arrays being value types.

I'm not going to argue about the ambiguity and parser complexity of int[] syntax either, that's totally valid points.

But there is still a pretty common PHPDoc syntax like that, see phpDocumentor docs, and it's used everywhere, like in Symfony code. Actually those PHPDocs combined with the PHPStorm's ability to parse and check them are our current substitute for typed arrays. So there are a lot of code with the int[] syntax and a lot of programmers used to write it. If the parser will only support the array<int> syntax, that will cause inconsistency between the new code and the old docs. I'm sure programmers will get used to the new syntax and the PHPDocs tools will support it shortly, but still there would be complaints about that.

/u/d_rbn is correct, these are magic methods

The real problem is though, the Magento developers were pretty inconstant on PHPDoc'ing the magic methods available. If you really want to get rid of this error, you would go into the various classes and add some PHPDoc notation to the class definition comment defining those functions.

Also they sometimes PHPDoc'd functions that they later implemented, causing more issues.

For example, the Mage_Catalog_Model_Product class (app/code/core/Mage/Catalog/Model/Product.php) should go from:

/** * Catalog product model * * @method Mage_Catalog_Model_Resource_Product getResource() * @method Mage_Catalog_Model_Resource_Product _getResource() *

to something more like

/** * Catalog product model * * @method Mage_Catalog_Model_Resource_Product getResource() * @method int getEntityTypeId() * @method Mage_Catalog_Model_Product setEntityTypeId(int $value) * @method int getAttributeSetId() * @method Mage_Catalog_Model_Product setAttributeSetId(int $value) * @method string getDescription() * @method Mage_Catalog_Model_Product setDescription(string $value) * @method Mage_Catalog_Model_Product setTypeId(string $value) * @method Mage_Catalog_Model_Product setPrice(float $value)

Standard documentation notation for any magic attribute you're looking to retrieve is:

@method {varType} get{AttributeName}() @method {currentClass} set{AttributeName}({varType} $value)

http://www.phpdoc.org/docs/latest/getting-started/your-first-set-of-documentation.html is a good starting place to learn PHPDoc if you don't know it.

No, those aren't annotations. Those are Docblock tags:

http://www.phpdoc.org/docs/latest/guides/docblocks.html#tags

The entire thing is a Docblock (not just the flowerbox)

If you read the slide that you linked, it actually did a pretty good job at explaining what annotations are.

An example of an annotation can be seen all over this page: http://doctrine-common.readthedocs.org/en/latest/reference/annotations.html

As you can see, annotations are more than just Docblock tags. Annotations are interpreted at runtime to have an added effect on the program. Docblock tags do not do this.

A few things I think are good to do:

• When naming files which are classes name them with "class" between the class name and the php extension e.g. Cart.class.php. I know you have them in a classes folder but I prefer that I can see straight away that it's a class file especially when I am doing a grep for code.
• Show what visibility your functions should have in a class e.g. public, private or protected - see http://uk1.php.net/protected. Right now in your cart class they are all implicitly public. You should make it clear that you intend those functions to be public.
• Add getters and setters for your Product class and make your properties private. This is how you should be accessing data from an object and not through accessing the properties directly. You should do the same for "count" in the Cart class.
• You are doing the calculation of the basket total outside of the basket. Why not do this inside the cart class?
  
• Last thing. Document your functions even if they are fairly straight forward. Use http://www.phpdoc.org/. It's good practice and allows others to interpret what your class and functions are meant to do.

1) Team meetings to discuss pain points, ideas, side projects, and deviations from the scope.

2) Learn to scope and understand the requirements.

3) Learn the code as best as you can (you don't need to fully understand it, just know what it does and the limitations) and never say "I don't want to hear about the technical stuff, just get the job done."

4) Tools (IDEs) don't matter, as long as they play nice with your repositories. Let the programmers use what they like. Ask them.

5) Learn how your code repository system works (git, svn, cvs, mercurial, the dreaded SourceSafe)

6) Peer review works. Let more than 1 person work on the same code. Have code review meetings, if applicable.

7) If a developer has an idea, listen to it and either let them work with it or shoot it down quickly. Any idea is a source for mental growth, even if it's a dead end. If it fails then you'll know not to go down that road again.

8) Enforce documentation in code (check out PHPDocumenter). Make a wiki for a knowledge base.