php / php/doc-en

language.namespaces.rationale first example doesn't actually explain what it is showing

Open
#3,154 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

On manual page: https://php.net/language.namespaces.rationale

This starts with an opening example Example #1 Namespace syntax example as defined in the docs code here.

However, this example block is hard to understand, and at present comes across as a bit of a dump of random examples without explanation. I think few newcomers to namespaces would understand what is being portrayed.

Issues are:

  • The title is 'Namespace syntax example' which implies a complete example how to create a namespace
  • It is unclear whether this is showing a range of examples, or whether this is intended to form a single script showing typical usage
  • Several of the sections in it have no description, so the reader is expected to figure out what is being shown despite the purpose of the page being an introduction
  • Some of the variables, e.g. $a, are reused within this block, implying that they are related.
  • The comment about global space isn't obviously referring to the starting \ character

Basically I think this section would be better rewritten for each example to have a comment on the line before summarising that language feature, and then the demonstration of the feature, and no re-use of variables, to avoid confusion.

Thank you to all contributors for the otherwise excellent documentation throughout the manual.

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 with language/namespaces.xml lines 53-70 and compare the current Example #1 with the language.namespaces.rationale manual page. Rewrite the example so each demonstrated feature has an explanatory comment, unrelated variables are not reused, and the global-space comment is explicit. Done means the opening example clearly introduces the namespace syntax without looking like a random collection of snippets.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.