php / php/doc-en

Inconsistent documentation and details about control structures.

Open
#1,739 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
XML
Stars
596
Forks
890
Avg merge
1d 15h
Merged PRs (30d)
55

Description

The docs have a section of control structures here, but it mostly contains the obvious ones. Any that could be misunderstood as a function is listed as functions, with a notice at the bottom of the page that looks like this.

CleanShot 2022-08-07 at 11 30 03

Pretty much every "function" in the reserved keywords list appears as a function based on its listing and the URL. https://www.php.net/manual/en/reserved.keywords.php

While investigating and trying to figure out a decent suggestion for how to list isset and the likes while keeping documentation about their signature, I noticed that there's an inconsistency with the way that control structures are detailed.

For example, while, if and for all have a section at the start which contains pseudo-code detailing the form, whereas do-while and switch have none. On top of this, the match page has an example of the structure using code that resembles PHP, which in my opinion is far superior.

Is there room to improve on this and make the documentation more consistent? I am more than happy to put some time in to do this work if there's some sort of consensus that could be reached.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the linked while, if, for, do-while, switch, and match pages with the control-structures and reserved-keywords pages. Establish a consensus on consistent structure notation and classification first; done means the agreed format is applied consistently to the relevant documentation entries.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.