Req #75527 [Opn->Csd]: Foreign return type syntax

Edit report at https://bugs.php.net/bug.php?id=75527&edit=1 ID: 75527 Updated by: salathe@php.net Reported by: jonathan at jjok dot co dot uk Summary: Foreign return type syntax -Status: Open +Status: Closed Type: Feature/Change Request Package: Doc Build problem PHP Version: Irrelevant -Assigned To: +Assigned To: salathe Block user comment: N Private report: N New Comment: Merged above PR. Previous Comments: ------------------------------------------------------------------------ [2017-11-15 00:57:00] salathe@php.net I've pushed a PR that should hopefully be a good starting point. See https://github.com/php/phd/pull/17 ------------------------------------------------------------------------ [2017-11-15 00:16:52] salathe@php.net 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 http://docbook.org/) and/or touching XML files en-masse (which makes life more difficult for the documentation translation team). ------------------------------------------------------------------------ [2017-11-14 21:08:34] danack@php.net Probably best asking in the docs group: http://news.php.net/group.php?group=php.doc https://secure.php.net/mailing-lists.php Or r11. ------------------------------------------------------------------------ [2017-11-14 20:56:36] 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. ``` <methodsynopsis> <methodname>json_decode</methodname> <methodparam><type>string</type><parameter>json</parameter></methodparam> <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> <returntype>mixed</returntype> </methodsynopsis> ``` 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 20:54:59] jonathan at jjok dot co dot uk Description: ------------ 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. ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=75527&edit=1