Documentation of special behaviour of magic methods

[beikov]

Because of the possibility to use __callStatic or __call, there should be a @method annotation which allows the developer to document these things. In addition to that, @property(-read/-write) should be included into the fields table with the keyword final if only read access is allowed and for write only something else. Write only for a property is bad practise, but PHP offers you that possibility...

[peej]

I don't understand what you mean, can you do an example?

[beikov]

I use this functionality in a similar way. It's just needed somehow in PHP because of the magic methods.

/**

• @property-read int $length

• @method Test getInstance returns a new instance

• @method-param int $initialValue getInstance The initial value for the object */ class Test{ public function __get($name) { if ($name == 'length') return $this->count(); return null; }

  public static final function __callStatic($name, $args) { if($name === 'getInstance') return new Test($args[0]); return null; } }

[ghost]

@peej, @redshadow159 is talking about object overloading.

That way of documenting "magic methods" is pretty clunky.

I propose that regular function/method docblocks be used, but that an added tag be used to indicate that the block is meant for a magic method.

For example:

<?php

    /**
     * @package SomePackage
     */
    class SomePackage
    {
        /**
         * Just calls sprintf() and returns the string.
         *
         * @access public
         * @param string $param1
         * @param integer $param2
         * @return string
         */
        public function doSomething ($param1, $param2)
        {
            return sprintf($param1, $param2);
        }

        /**
         * Performs different operations depending on argument types.
         *
         * @access public
         * @param string $method
         * @param array $args
         * @return mixed
         */
        public function __call ($method, $args)
        {
            if (is_integer($args[0]))
            {
                return array_sum($args);
            }

            else
            {
                return join(' ', $args);
            }
        }

        /**
         * Sums up the two integers.
         *
         * @magic
         * @access public
         * @param integer $param1
         * @param integer $param2
         * @return integer
         */

        /**
         * Concatenates the two strings together.
         *
         * @magic
         * @access public
         * @param string $param1
         * @param string $param2
         * @return string
         */
    }

Doing it this way gives us the benefit of everything we can already do in non-magic method docblocks, as well as it being easily understood by developers what those docblocks are for.

[peej]

Hi Kevin, I like this approach to handling the __call magic method. You'd need to optionally specify the method name too, perhaps as part of the @magic tag.

[ghost]

Ah, yes, I didn't think about that!

I agree with you on using the @magic to define the magic method's name.

I can't think of any other magic-specific value that would need to be set to justify creating additional @magic tags.

[ghost]

I'm looking at tackling this issue, mind telling me where I can start?

Where should I look at to start making tweaks?

[peej]

It's quite a difficult one actually now that I think about it. The parser works by reading doccomments into a buffer and then continuing until it finds an element that we document, applying the previously captured doccomment content to it. In this case, there is no element to find, just the doccomment, so the methodDoc object we need to create will have to be done when the doccomment is processed and a @magic tag is discovered.

Look at line 630 of phpDoctor.php, this is where the doccomments are parsed and buffered. A quick check somewhere here to see if the doccomment contains a @magic tag and if so create a methodDoc would probably do the trick.