Order of tags in the php doc

Question

What is the exact order of tags in php doc? is there some convention to follow? or it's "random"?. for example:

     * Some instructions 
     * @example $entity->id; $entity->content ...
     * @throws MyException
     * @return mixed
     * @see ThisClass

     * Some instructions 
     * @throws MyException
     * @example $entity->id; $entity->content ...
     * @see ThisClass
     * @return mixed

are so far "Equivalent" ?

Answer 1

The order of the tags doesn't affect the /rendered output/ if you are building html/chm's via phpdocumentor, nor the code-assist in IDE's.

However the docblock needs to be readable in-place, and as @van suggests, consistency would help you and other developers find information quickly. I think of it like a .md file, it should be readable rendered or raw.

I've been using php docblocks for probably 10yrs and tend to use the following format.

/**
* One-line introduction followed by a full stop (for the title in some templates).
*
* @deprecated this should be prominent so I often put it at the top!
* @todo Critical TODO ... this function doesn't work yet!
* 
* A fuller paragraph detailing stuff.
* A fuller paragraph detailing stuff.
* A fuller paragraph detailing stuff.
* @see is part of the detail
* @example is part of the detail
*
* @todo following on from the detail - what's not been done.
* @todo polishing not done, N2H's.
* 
* @throws and other technical aspecs I'd put here - if any.
* 
* @param Then params in a block - in the ACTUAL order of the params
* @param phpstorm always separates the last param from return
* @param with blank line so i've started going with that!
* 
* @return is always the last tag - makes sense.
*/ 

The one line intro is a hangover from PHPDocumentor 1, which had that as a requirement with a full stop. On index pages and and navigation this is all you see. So I still do it.

I tend to order things in the order you'd want to read them - quite simply. Prioritise show-stoppers like deprecation - to not waste people's time reading a dead function. If there's a critical TODO (i.e. the class/method isn't finished) I'd put that right at the top, optional todo's (nice to haves, phase 2...) can go later.

And I'd separate blocks of similar things with spaces.

This makes sense to me, but it's partly a style/familiarity thing.

Answer 2

The order is irrelevant and I don't know any convention for it. However I would suggest to always use the same order, as it improves readability.