Rendered XML/JSON documentation is inconsistent and incomplete

Start with ide-json/array_key_first.json and its corresponding XML output, then trace how the renderer handles return types and parameter initializers. Compare array_key_first, str_pad, and stream_socket_server against their source documentation. Done means the rendered JSON and XML preserve union return types and initializer values consistently.

It looks like the rendered JSON/XML files are missing some cruicial information.

For example, array_key_first has a return type of int|string|null.

Looking at ide-json/array_key_first.json:

{
    "name": "array_key_first",
    "purpose": "Gets the first key of an array",
    "manualid": "function.array-key-first",
    "version": "PHP 7 >= 7.3.0, PHP 8",
    "params": {
        "array": {
            "name": "array",
            "type": "array",
            "optional": "false",
            "description": "..."
        }
    },
    "currentParam": null,
    "return": {
        "type": "null",
        "description": "..."
    }
}

We can see the return type is simply null. This is also the case in the xml version:

<?xml version="1.0" encoding="UTF-8"?>
<function>
<name>array_key_first</name>
<purpose>Gets the first key of an array</purpose>
<manualid>function.array-key-first</manualid>
<version>PHP 7 &gt;= 7.3.0, PHP 8</version>
<params>
  <param>
    <name>array</name>
    <type>array</type>
    <optional>false</optional>
    <description><![CDATA[<p class="para">
      An array.
     </p>]]></description>
  </param>
</params>
<return>
  <type>null</type>
  <description>...</description>
</return>
</function>

This inconsistency / incompleteness can also be observed with the initializer of default parameters.

For example, the str_pad function:

{
    "name": "str_pad",
    "purpose": "Pad a string to a certain length with another string",
    "manualid": "function.str-pad",
    "version": "PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8",
    "params": {
        "string": {
            "name": "string",
            "type": "string",
            "optional": "false",
            "description": "..."
        },
        "length": {
            "name": "length",
            "type": "int",
            "optional": "false",
            "description": "..."
        },
        "pad_string": {
            "name": "pad_string",
            "type": "string",
            "optional": "true",
            "initializer": "\" \"",
            "description": "..."
        },
        "pad_type": {
            "name": "pad_type",
            "type": "int",
            "optional": "true",
            "description": "..."
        }
    }
}

We can see there is an initializer for pad_string but no initializer value for pad_type.

I had a quick look at the implementation and I think this is due to the fact that pad_type has an initializer of <constant>STR_PAD_RIGHT</constant> instead of just the text STR_PAD_RIGHT.

Another example would be stream_socket_server where the initializer is just the literal text STREAM_SERVER_BIND | STREAM_SERVER_LISTEN:

{
    "name": "stream_socket_server",
    "purpose": "Create an Internet or Unix domain server socket",
    "manualid": "function.stream-socket-server",
    "version": "PHP 5, PHP 7, PHP 8",
    "params": {
        "address": {
            "name": "address",
            "type": "string",
            "optional": "false",
            "description": ""
        },
        "error_code": {
            "name": "error_code",
            "type": "int",
            "optional": "true",
            "description": ""
        },
        "error_message": {
            "name": "error_message",
            "type": "string",
            "optional": "true",
            "description": ""
        },
        "flags": {
            "name": "flags",
            "type": "int",
            "optional": "true",
            "initializer": "STREAM_SERVER_BIND | STREAM_SERVER_LISTEN",
            "description": ""
        },
        "context": {
            "name": "context",
            "type": "null",
            "optional": "true",
            "description": ""
        }
    }
}

I do wonder if this is a known limitation of the current renderer and if there is any current effort of fixing this?