phpDoc

delayedinsanity · 05-31-2008, 04:58 PM

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

Quote:

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:

PHP Code:


			
..end of file-level Docblock */

include($_SERVER['DOCUMENT_ROOT'].'/bin/lib/tuatara.config.php');

// Session is instantiated within controller
tuatara::loadEmpty('core', 'session');

// Page Specific
 $szCommand = (array_key_exists('cmd', $_GET)) ? $_GET['cmd'] : 'logout';
new controller($szCommand);

/**
 * ..start of class-level Docblock..

Is that incorrect?
-m

delayedinsanity · 05-31-2008, 05:31 PM

Another minor question, if I have a function that just includes another file, would that be considered a void return, or what do you use?
-m

Kalle · 06-01-2008, 04:42 PM

The @package command is used at the page level docblock and the class level docblock like below:

PHP Code:


			
<?php

    /**

     * @author    Kalle Sommer Nielsen <kalle@php.net>

     * @package    TalkPHP

     */





    /**

     * Some external class

     *

     * @author    TalkPHP Community <community@talkphp.com>

     * @package    TalkPHP_External

     */

    class TalkPHP_External

    {

        /* ... */

    }

?>

=)

wGEric · 06-04-2008, 12:07 AM

I believe you have to have an empty block before any code. I'm not sure though. Something like

PHP Code:


			
..end of file-level Docblock */



/**

*/



include($_SERVER['DOCUMENT_ROOT'].'/bin/lib/tuatara.config.php');



// Session is instantiated within controller

tuatara::loadEmpty('core', 'session');



// Page Specific

 $szCommand = (array_key_exists('cmd', $_GET)) ? $_GET['cmd'] : 'logout';

new controller($szCommand);



/**

 * ..start of class-level Docblock..

delayedinsanity · 06-04-2008, 12:20 AM

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.
-m

xenon · 06-04-2008, 06:44 PM

You got the idea the wrong way. The page-level doc-block represents a description of the entire file, whilst a class-level doc-block represents a description for that class only. Example:

PHP Code:


			
<?php
/**
 * PAGE LEVEL DOC BLOCK
 *
 * @package main
 */

/**
 * CLASS LEVEL DOC BLOCK
 *
 * @package core
 * @subpackage classes
 */
class TestClass
{
   // ...
}

About your minor question, yes, but you don't need to add a @return void statement to your function comment, void is implied if no return statement is supplied.

delayedinsanity · 06-04-2008, 07:23 PM

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.
-m

wGEric · 06-04-2008, 10:04 PM

@ignore might be useful in the empty block.