|  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Request #75527 Foreign return type syntax
Submitted: 2017-11-14 20:54 UTC Modified: 2018-11-12 21:09 UTC
From: jonathan at jjok dot co dot uk Assigned: salathe (profile)
Status: Closed Package: Doc Build problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2017-11-14 20:54 UTC] jonathan at jjok dot co dot uk
I noticed that the documentation still uses Java/C# style return types, even though PHP now has its own syntax for return types. For exmaple:

mixed json_decode ( string $json )

instead of:

json_decode ( string $json ) : mixed

It would be nice to see the documentation reflect the syntax of the language.


Add a Patch

Pull Requests

Add a Pull Request


AllCommentsChangesGit/SVN commitsRelated reports
 [2017-11-14 20:56 UTC] jonathan at jjok dot co dot uk
I've been having a look into this. I think a few changes will need to be made to make this happen.

1. I think a new `returntype` needs to be added in the formatter classes in this package. eg `Package_Generic_XHTML`. I don't think `type` can be reused as it is used anywhere a type is mentioned in the docs, not just return types, and the return type needs to be formatted differently. eg `sprintf(' : <span>%s</span>')`

2. I think the docbook schema in the `phpdoc` repository needs to be updated to allow a new `returntype` element.

   <methodparam choice="opt"><type>bool</type><parameter>assoc</parameter><initializer>false</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>depth</parameter><initializer>512</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
3. All the existing documentation needs to be updated to the new format. :O

Let me know if I'm on the right tracks. Thanks.
 [2017-11-14 21:08 UTC]
Probably best asking in the docs group:

Or r11.
 [2017-11-15 00:16 UTC]
We should be able to do this without touching the source XML files, by changing how and where PhD renders the return-type-specific <type> elements. It has been a while since I touched PhD but it feels like something that can be done relatively easily.

We definitely want to avoid adding new elements to DocBook (which isn't something our project owns: see and/or touching XML files en-masse (which makes life more difficult for the documentation translation team).
 [2017-11-15 00:57 UTC]
I've pushed a PR that should hopefully be a good starting point.
 [2018-11-12 21:09 UTC]
-Status: Open +Status: Closed -Assigned To: +Assigned To: salathe
 [2018-11-12 21:09 UTC]
Merged above PR.
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Thu Oct 28 16:03:36 2021 UTC