PHP methods being referenced incorrectly in Twig based template #1087

Closed
mbabker opened this Issue Dec 1, 2013 · 5 comments

Comments

Projects
None yet
2 participants

mbabker commented Dec 1, 2013

Using a Twig based template for api.joomla.org (based off the responsive-twig template), PHP methods which are referred to in a @see tag incorrectly have the namespace of the current class prepended. See http://api.joomla.org/framework-1.0/classes/Joomla.Application.AbstractWebApplication.html (protected method checkConnectionAlive) for example.

Below is the code I'm using to parse the @see tag in the template.

{% if (tag.name == "see") %}
    {% if tag.reference|slice(1, 4) == "http" %}
        <a href="{{ tag.reference|slice(1) }}" target="_blank">{{ tag.reference|slice(1)|markdown|raw }}</a>
    {% else %}
        {{ tag.reference|route|raw }}
    {% endif %}
{% endif %}
Owner

mvriel commented Dec 11, 2013

You have used the following line: @see connection_status().

In this case phpDocumentor searches for a function (not method) called connection_status() and since this is namespaced code, and this is not a fully qualified location, it will assume that this is relative to the current namespace.

It was only during your report that I noticed that this is not consistent with the original implementation of @see; so this would appear to be an implementation error that needs to be fixed. Though we do need to find a way to discern the difference between a global function and method (up til now methods were referred to as self::methodname()).

@mvriel mvriel modified the milestone: 2.4, 2.3 Feb 16, 2014

Owner

mvriel commented Mar 26, 2014

@ossh mentions in #1142 that the same behaviour also occurs when you use an @see to link to a url, such as @see http://phpdoc.org

@mvriel mvriel modified the milestone: 2.5, 2.4 Mar 30, 2014

@mvriel mvriel modified the milestone: 2.6, 2.5 May 17, 2014

Owner

mvriel commented May 18, 2014

I have done a test implementation with the following example:

<?php
namespace {
    function myFunction(){}
    function myFunction2(){}

    class A {
        public $myProperty;

        public function myFunction() {}

        /**
         * @see myFunction()
         * @uses myFunction()
         */
        public function refersToMyFunction(){}
    }
}

namespace My\Space {
    function myFunction3(){}

    class A {
        public $myProperty;

        public function myFunction() {}

        /**
         * @see $this
         * @see self
         * @see \A
         * @see A
         * @see $myProperty
         * @see self::$myProperty
         * @see \A::$myProperty
         * @see myFunction()
         * @see myFunction2()
         * @see myFunction3()
         * @see self::myFunction()
         * @see \myFunction()
         * @see \A::myFunction()
         * @see http://phpdoc.org
         * @uses myFunction()
         */
        public function refersToMyFunction(){}
    }
}

(there are a fair amount of permutations)

I am going to clean up the code and commit it

mvriel was assigned by mbabker May 19, 2014

@mvriel mvriel added a commit to mvriel/phpDocumentor2 that referenced this issue May 19, 2014

@mvriel mvriel #1087: Fully support `@see`
In our documentation we have included that `@see` should be able to cope with
URLs, references to FQSEN's but also that a function/method name without anything
in front of it may either refer to a method in the current class, or a function
in the current namespace.

This type of relation was not supported by phpDocumentor because of the decoupled
nature of its architecture. In order to properly support this I have introduced a
meta type called `@context` that is translated in the linked to either the current
class or the current namespace.

So for example:

    `@see myFunction()` on a method in a class either refers to a method of said
    class if it exists; or if it doesn't it refers to a function in the namespace
    of the class.
0373e24
Owner

mvriel commented May 19, 2014

I have issued PR #1270 to resolve this item; it will be included in the next release of phpDocumentor. Thanks for reporting this issue; it is great having it fixed.

mvriel closed this May 19, 2014

mvriel removed the in progress label May 19, 2014

mbabker commented May 19, 2014

👍

@ashnazg ashnazg added a commit that referenced this issue May 22, 2014

@ashnazg ashnazg Merge pull request #1270 from mvriel/feature/1087
#1087: Fully support `@see`
d8f9b46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment