So I finally made the jump from using my pseudo docblock format of commenting to making it phpDoc compliant. I haven't finished recommenting everything yet, so I haven't run it through phpDoc, but I have a question.
In one of my books which has a chapter on phpDoc, it states
A file comment should be the first DocBlock in a document. It should contain a @package tag, and it should not directly precede a coding construct. In other words, if you add a file-level Docblock, you should ensure that you also add a class-level comment before the first class declaration.
So here's my question. That makes it sound like a class level DocBlock should almost if not directly follow a file level DocBlock. What if I have an include and a few commands first, ie:
I'm three files away from finishing adding docblocks to my code... took almost as long as coding, I think, but that could be partially due to the fact that it's the first time I've open a few classes in a while and I did a lot of tidying up at the same time.
When I'm done I'll run phpDoc on it and see if it throws out any warnings or flips me off, you know any of the regular stuff, and whatever the result I'll post here just so it's there for reference. Not that anybody has ever been known to use a forums search feature anyways, but just in case.
I don't think I have the wrong idea though. I know what the difference is between a page level and a class level docblock. I was curious if the page-level one would be ignored or reference improperly due to the fact that I had pagedocblock->include()->classdocblock and according to 'http://phpdocu.sourceforge.net/howto.php' I was right. If there's any code construct immediately following the page level docblock, it's no longer considered a page-level but instead a docblock for that construct, even if it's as simple as defining a variable or constant. So it would seem wGEric has the right idea, include a third docblock that's either empty or includes a short description of what's going on between the page level and class level.
I wasn't aware however that if a return was void you could omit the statement, thank you. I think, partially since I've already included them everywhere and partially because I just think the word void sounds cool.