Merge pull request #29 from ramsey/return-object

Link body of return type to the xref for the type

Author: markstory

doc/reference.rst

@@ -88,7 +88,8 @@ Each directive populates the index, and or the namespace index.
         
             :param string $one: The first parameter.
             :param string $two: The second parameter.
-            :returns: An array of stuff.
+            :returns: A description of what this returns.
+            :returntype: LibraryName\\LibraryClass
             :throws: InvalidArgumentException
         
            This is an instance method.

requirements.txt

@@ -1 +1 @@
-sphinx>=1.3, <2.3
+sphinx>=1.3, <2.5

sphinxcontrib/phpdomain.py

@@ -128,7 +128,7 @@ class PhpObject(ObjectDescription):
         Field('returnvalue', label=_('Returns'), has_arg=False,
               names=('returns', 'return')),
         Field('returntype', label=_('Return type'), has_arg=False,
-              names=('rtype', 'returntype')),
+              names=('rtype', 'returntype'), bodyrolename='obj'),
     ]
 
     def get_signature_prefix(self, sig):

test/test_doc.rst

@@ -424,3 +424,51 @@ Test Case - Test subpackage links
 :php:class:`LibraryName\\SubPackage\\SubpackageInterface`
 
 :php:exc:`LibraryName\\SubPackage\\NestedNamespaceException`
+
+Return Types
+============
+
+.. php:namespace:: OtherLibrary
+
+.. php:class:: ReturningClass
+
+    A class to do some returning.
+
+    .. php:method:: returnClassFromSameNamespace()
+
+        :returns: An object instance of a class from the same namespace.
+        :returntype: OtherLibrary\\ReturnedClass
+
+    .. php:method:: returnClassFromOtherNamespace()
+
+        :returns: An object instance of a class from another namespace.
+        :returntype: LibraryName\\SubPackage\\SubpackageInterface
+
+    .. php:method:: returnClassConstant()
+
+        :returns: The value of a specific class constant.
+        :returntype: LibraryName\\NamespaceClass::NAMESPACE_CONST
+
+    .. php:method:: returnGlobalConstant()
+
+        :returns: The value of a specific global constant.
+        :returntype: SOME_CONSTANT
+
+    .. php:method:: returnExceptionInstance()
+
+        :returns: An instance of an exception.
+        :returntype: InvalidArgumentException
+
+    .. php:method:: returnScalarType()
+
+        :returns: A scalar string type.
+        :returntype: string
+
+    .. php:method:: returnUnionType()
+
+        :returns: Any of a whole bunch of things specified with a PHP 8 union type.
+        :returntype: int|string|OtherLibrary\\ReturnedClass|LibraryName\\SubPackage\\SubpackageInterface|null
+
+.. php:class:: ReturnedClass
+
+    A class to return.