search

php / doc-en

English PHP documentation
476 stars 708 forks source link

Document missing internal global constants #2747

Open kocsismate opened 10 months ago

kocsismate commented 10 months ago

The following internal global constants are not yet documented:

The following global constants aren't documented on a predefined constants page, but described somewhere else (e.g. on class or function manual pages):

ekinhbayar commented 9 months ago

In the hopes of being helpful for some of these... I went through the cURL constants listed here, making some notes:

getinfo page has these constants listed with brief explanations:

CURLINFO_HTTP_CONNECTCODE CURLINFO_HTTPAUTH_AVAIL CURLINFO_PROXYAUTH_AVAIL CURLINFO_OS_ERRNO CURLINFO_NUM_CONNECTS CURLINFO_SSL_ENGINES CURLINFO_COOKIELIST CURLINFO_FTP_ENTRY_PATH CURLINFO_APPCONNECT_TIME CURLINFO_CERTINFO CURLINFO_CONDITION_UNMET CURLINFO_RTSP_CLIENT_CSEQ CURLINFO_RTSP_CSEQ_RECV CURLINFO_RTSP_SERVER_CSEQ CURLINFO_RTSP_SESSION_ID

predefined constants page has this one listed with a brief explanation. usually this page mentions only the curl & php version the constant was made available, unlike this case:

CURLOPT_ISSUERCERT

setopt page has these listed with a brief explanation:

CURLOPT_RESOLVE CURLOPT_HTTP09_ALLOWED CURLOPT_SAFE_UPLOAD

the options below are mentioned under the CURLOPT_PROTOCOLS documentation under the setopt page, they are all available bitmask values for CURLOPTPROTOCOLS. I'm not sure if there's further need to explain each of them? however, they are missing from the predefined constants page. In fact, if I look at the predefined constants page, I only see three CURLPROTO* listed (_SMB, _SMBS, _MQTT) - I think this page needs some love :) either to fix the inconsistency or, well, have some method to the madness :D

CURLPROTO_ALL CURLPROTO_DICT CURLPROTO_FILE CURLPROTO_FTP CURLPROTO_FTPS CURLPROTO_HTTP CURLPROTO_HTTPS CURLPROTO_LDAP CURLPROTO_LDAPS CURLPROTO_SCP CURLPROTO_SFTP CURLPROTO_TELNET CURLPROTO_TFTP

further FYI, the options below aren't mentioned under CURLOPT_PROTOCOLS but are in the list of constants in this issue:

CURLPROTO_GOPHER CURLPROTO_IMAP CURLPROTO_IMAPS CURLPROTO_POP3 CURLPROTO_POP3S CURLPROTO_RTSP CURLPROTO_RTMP CURLPROTO_RTMPE CURLPROTO_RTMPS CURLPROTO_RTMPT CURLPROTO_RTMPTE CURLPROTO_RTMPTS CURLPROTO_SMTP CURLPROTO_SMTPS

the rest of the cURL constants listed here aren't found in getinfo, setopt or predefined constants pages.

I hope this helps!

kocsismate commented 9 months ago

Hi @ekinhbayar Thanks for your help!

I think we should settle on some convention how to document global constants. Now, they can be either documented on method synopses pages or in the predefined constant pages, or rarely on class synopses pages (https://www.php.net/manual/en/class.datetimeinterface.php#datetimeinterface.constants.atom). IMO this is not an ideal case since there is not a single source of truth and autogeneration/detection of global constants is difficult.

That's why I believe all global constants should be displayed on a predefined constant page, and we could reference them from other pages (the format parameter of https://www.php.net/manual/en/datetime.format.php is a good example where the description of a constant is referenced).

ekinhbayar commented 9 months ago

@kocsismate I agree that there should be a single source of truth for predefined constants. Documenting them on the predefined constants page and referencing it everywhere applicable makes sense to me. It'd be a biiig change but in the long term it could make maintenance easier. If this, or any other alternative solution gets settled on, I'd be happy to help with the work needed for it.

haszi commented 6 months ago

I'd like to start working on the cURL constants. As the first steps, I'd like to add <variablelist>s for each related set of constants on the predefined constants page, move all the constants form the function pages to under the appropriate <variablelist> and link to these from the functions' pages. Based on the previous discussion on this issue kocsismate and ekinhbayar, I think this should not be an issue.

What I do have a question about is formatting of the predefined constants page. After moving the constants there and breaking these up into appropriate lists/sections/groups, may I format these as tables or do you need me to convert the tables I'm moving from the functions' pages to match the format of the predefined constants. I personally prefer tables, as I think the <variablelist> and their <title>s currently just don't add enough visual separation between the distinct set of constants, but either way is fine for me.

kocsismate commented 6 months ago

What I do have a question about is formatting of the predefined constants page. After moving the constants there and breaking these up into appropriate lists/sections/groups, may I format these as tables or do you need me to convert the tables I'm moving from the functions' pages to match the format of the predefined constants.

Good question... Neither I'm sure. I also like the formatting of tables, but they are more difficult to autogenerate (mostly because the content of the preexisting ones differ in some cases). We had some conversation somewhere with @Girgias about the pros and cons of tables, but I couldn't find it now... However, I agree that we should come to a conclusion about the used formatting.

Girgias commented 6 months ago

Nothing prevents us from rendering a <variablelist> with a role="constant_list" attribute as a table in PhD. I think most constant pages actually use a <variablelist> and not a table for markup, and I would prefer standardizing the markup to that. As a table is very generic.

haszi commented 5 months ago

And the header rows of these tables would be marked with an attribute/value too? E.g. role="header_row"?

This may already have an established standard, but how could these tables be grouped? I'm looking at the cURL docs and the constants under the value parameter of curl_setopt() are a great example of this. It lists the values that can be passed to the $value parameter in 7 separate tables, based on the type that can be used with each cURL option. Should these 7 tables be wrapped in another tag so that the value type could be mentioned above the table, or should the title of the table show the type or should this really be one table with an additional column showing the type of value these options accept?

Girgias commented 5 months ago

And the header rows of these tables would be marked with an attribute/value too? E.g. role="header_row"?

Those should be easy to generate within PhD as most tables just have 3 columns, the constant name, the value (which should be removed), and the description. Which is basically what corresponds to the term tag and the listitem tag.

This may already have an established standard, but how could these tables be grouped? I'm looking at the cURL docs and the constants under the value parameter of curl_setopt() are a great example of this. It lists the values that can be passed to the $value parameter in 7 separate tables, based on the type that can be used with each cURL option. Should these 7 tables be wrapped in another tag so that the value type could be mentioned above the table, or should the title of the table show the type or should this really be one table with an additional column showing the type of value these options accept?

I'm not sure that curl docs are what I would call amazing. :/

It might make sense to have lists of the sort: the following constants require a value of type TYPE: LIST, OF, CONSTANTS but then again maybe completely rethink the cURL docs is a good idea.

haszi commented 5 months ago

So Phd could render the constant lists with the appropriate attribute as a table. I'm assuming this is a theoretical possibility at this point, right?

If so, I could go through the all the constant tables / lists in cURL and make sure they're all in a format that would easily lend itself to be converted to the <variablelist> format.

E.g. 

<tbody>
  <row>
    <entry></entry>
    <entry></entry>
  </row>
</tbody>

which could easily be converted to 

<variablelist>
  <varlistentry>
    <term></term>
    <listitem></listitem>
  </varlistentry>
</variablelist>

This way all the constant lists' formatting could be synced up and all constants could be moved to the constants page (with a <xi:include> on the page they've been moved from). This would make for a standard, easy to convert format and no visible change on the functions' pages (other than the few that contain lists being converted to tables).

In addition, I could add all the missing constants to the table(s) without having to worry about formatting. :-)

Girgias commented 5 months ago

Yes PhD doesn't support this yet, but I don't think it should be too hard (for PhD standards as that codebase is... interesting).

Having a consistent formatting on a page should also allow the php-src genstub.php script to be able to generate/update the appropriate pages too, something it can't actually do at the moment :/

If you could go through this that would be great, although I might wait before merging some of the PRs depending on the impact for translations.

haszi commented 5 months ago

I've just checked the four cURL functions that list constants in their parameter descriptions. All but one, which is using a <variablelist> instead of an <informaltable>, are using a table format that is compatible with a <variablelist> except that some of these tables have a third, Notes column. This is usually used for notes on the first version of cURL and/or PHP these constants is available on.

I'll convert the list on the curl-getinfo() page to the same table format other cURL tables use and I'll submit a PR. Can I go ahead an convert the constants page to tables in one PR and follow that up with another PR moving the tables from the four functions' pages there? Or just move the tables to the constants page first?

haszi commented 5 months ago

I've just opened the first PR for the standardizing the tables for the cURL constants (and later to move all tables to the constant list page).

If you could go through this that would be great, although I might wait before merging some of the PRs depending on the impact for translations.

If that is any help and speeds up things, I could do the "manual labor" part of converting the curl_getinfo() lists in the translations as well, and later I could move the tables to the constant list page too for each translation.

Girgias commented 5 months ago

I've just opened the first PR for the standardizing the tables for the cURL constants (and later to move all tables to the constant list page).

If you could go through this that would be great, although I might wait before merging some of the PRs depending on the impact for translations.

If that is any help and speeds up things, I could do the "manual labor" part of converting the curl_getinfo() lists in the translations as well, and later I could move the tables to the constant list page too for each translation.

The main issue is that the translation might not be up-to-date already, you can have a look at http://doc.php.net/ FR, JA, RU, DE and ZH are roughly up-to-date, however ES (Spanish) is very outdated in general.

But doing the work would be appreciated :)

haszi commented 1 week ago

Could someone remove the below four PostgreSQL constants from this list as the PR adding them was reverted?

PGSQL_PIPELINE_SYNC PGSQL_PIPELINE_ON PGSQL_PIPELINE_OFF PGSQL_PIPELINE_ABORTED

kocsismate commented 1 week ago

Could someone remove the below four PostgreSQL constants from this list as the https://github.com/php/php-src/pull/12735?

Done :)