After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 552605 - Add support for PHP namespaces
Add support for PHP namespaces
Status: RESOLVED FIXED
Product: doxygen
Classification: Other
Component: general
1.5.8
Other All
: Normal enhancement
: ---
Assigned To: Dimitri van Heesch
Dimitri van Heesch
: 576911 (view as bug list)
Depends on:
Blocks:
 
 
Reported: 2008-09-17 09:43 UTC by Karsten Dambekalns
Modified: 2011-03-20 23:52 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Karsten Dambekalns 2008-09-17 09:43:46 UTC
PHP 5.3 introduces namespaces, for which support on Doxygen is missing.

It is not yet fully clear whether PHP will use "namespace X::Y::Z;" or rather "namespace X::Y::Z { ... }" but this is about everything that remains to be seen. One developer hinted at the possibility of another slight change to namespace syntax, I'll keep this feature request updated.

It should basically be enough if doxygen treats "namespace X::Y::Z;", as if "namespace X { namespace Y { namespace Z {" had been written in C#/C++ (where the closing }'s are all at the end of the file. But mind that there might be multiple namespace declarations in one PHP file, so in that case it needs to act as if the closing } is before that next namespace declaration.

Here is the PHP documentation on namespaces: http://www.php.net/manual/language.namespaces.php

And here is (part of) our code making use of namespaces, if you want to to have a look or need to code to test Doxygen on: https://svn.typo3.org/FLOW3/Packages/FLOW3/trunk/Classes/
Comment 1 Karsten Dambekalns 2008-12-15 17:54:56 UTC
Recently the PHP developers published PHP5.3.0alpha3 which includes the new syntax for namespaces. There was a switch from :: as namespace seperator to \ and now both ways of declaring a namespace (one being "namespace some\ns;" which is in effect from that point on until a new namespace is declared, the other being "namespace some\ns { ... }" doing what one would expect) are possible.

The URLs mentioned above are still good, the PHP documentation has been updated accordingly and we have switched our codebase to the new syntax.

Please, help us poor developers by at least giving us back one piece of our currently broken tool chain! ;)
Comment 2 Karsten Dambekalns 2009-01-16 11:28:31 UTC
If there is anything I can do to help with this, let me know. We currently have no way of producing code documentation, so we really long for a solution. :)
Comment 3 Karsten Dambekalns 2009-05-26 09:22:39 UTC
Oh, well, then it'll be some other tool... thanks anyway!
Comment 4 Dimitri van Heesch 2009-06-02 19:05:32 UTC
A patch with the solution would be nice ;-)

Anyway, once namespaces become "non-alpha" they will probably be 
added to doxygen. Hopeful the developers will come to their senses 
and use :: i.s.o. \ as the scope operator before that happens.
Comment 5 Karsten Dambekalns 2009-06-02 21:34:26 UTC
He, nothing alpha about namespaces - PHP 5.3 is in release candidate status by now and the backslash will definitely stay...
Comment 6 Mangirdas 2010-04-09 12:37:38 UTC
PHP 5.3 is stable for a long time now. Doxygen will support php namespaces or not?
Comment 7 Fabien Udriot 2010-08-25 12:48:15 UTC
Is there any progress on this one? 

I tested again with the latest Doxygen 1.7.1 but didn't see any improvement regarding namespaces. I admit namespaces looks a bit weird in PHP compared to other language but it is really a missing feature for me.

namespace MyApp\Web\Routing;
Comment 8 Dimitri van Heesch 2010-08-28 16:53:04 UTC
*** Bug 576911 has been marked as a duplicate of this bug. ***
Comment 9 Dimitri van Heesch 2010-08-28 16:58:47 UTC
The implementation of namespace support for PHP consists of 3 parts:
1) getting doxygen to parse PHP namespaces (including the "get" and "get as" constructs)
2) allowing references to qualified items from the documentation.
3) getting the source browser and cross referencing features to recognise qualified names and do proper name resolution.

I'm current working on 1, which should be available in the next subversion update.
Comment 10 Fabien Udriot 2010-08-28 17:19:03 UTC
Great to hear that! Thanks for taking care...
Comment 11 faeroth 2010-08-30 14:33:34 UTC
(In reply to comment #9)
> The implementation of namespace support for PHP consists of 3 parts:
> 1) getting doxygen to parse PHP namespaces (including the "get" and "get as"
> constructs)
> 2) allowing references to qualified items from the documentation.
> 3) getting the source browser and cross referencing features to recognise
> qualified names and do proper name resolution.
> 
> I'm current working on 1, which should be available in the next subversion
> update.

Awesome job!

I am not sure whether you know, but there is yet another thing about namespaces in PHP that you might want to implement.
PHP offers the possibility of 'switching' into a namespace by just putting a semicolon after the name instead of curly brackets containing the namespace's code.
Thus,
   namespace A;
   class B {
   }
   namespace C;
   class C {
   }
   
is the same as
   namespace A {
      class B {
      }
   }
   namespace C {
      class C {
      }
   }

For verification, check out http://www.php.net/manual/en/language.namespaces.definitionmultiple.php .

It would be very great if you implemented this feature as well.

Thanks.
Comment 12 Dimitri van Heesch 2010-09-25 10:06:01 UTC
The PHP namespace support changes have been commited to SVN.
Let me know if you see any issues.
Comment 13 Dimitri van Heesch 2010-10-09 08:19:59 UTC
This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.7.2. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information
that you think can be relevant.
Comment 14 account 2010-11-21 23:01:14 UTC
Version 1.7.2 seems not to be able to handle namespaced classnames for parameters and return values of methods.

E.g.

MyClass.php:
  namespace MyNamespace;
  class MyClass {
    ...
  }

ExampleClass.php:
  class ExampleClass {
    /**
     * @var \MyNamespace\MyClass
     */
    public exampleMember = null;
  }

Instead doxygen outputs warnings like "documented function `MyNamespace MyClass' was not declared or defined".
Comment 15 Dimitri van Heesch 2010-11-22 19:42:33 UTC
(In reply to comment #14)
> ExampleClass.php:
>   class ExampleClass {
>     /**
>      * @var \MyNamespace\MyClass
>      */
>     public exampleMember = null;
>   }
> 
> Instead doxygen outputs warnings like "documented function `MyNamespace
> MyClass' was not declared or defined".

I don't understand the use of @var in your example. What are you trying to accomplish? Or did you mean to use @ref instead?
Comment 16 account 2010-11-23 10:43:27 UTC
@var indicates the type of the member variable, which could be used in the documentation to link to the according class (while "array" would also be a valid type as far as i know).
IDEs like Eclipse PDT use this indication in order to provide specific auto-completion.
Comment 17 account 2011-03-20 23:52:29 UTC
Please set the status of this issue to "open" until the stated issue with namespaced classes in @var is resolved.