Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Rendered XML/JSON documentation is inconsistent and incomplete

Ouverte
  • Quelque chose ne va pas ?
#269 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
50/100
Type d'issue
Bug
Clarté
Plutôt claire
Activité
Active
Stack technique
php
Domaine
documentation

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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?

Langage dominant
PHP
Étoiles
91
Forks
59
Aucune PR mergée en 30 j

Préparer son environnement

Nous n'avons pas encore vérifié les fichiers d'installation de ce projet. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de php/phd

Toutes les issues de php/phd

Issues similaires

Plus d'issues PHP

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.