php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #73117 Documentation for multiple namespaces in one file needs a clarification.
Submitted: 2016-09-19 23:53 UTC Modified: 2016-09-20 14:12 UTC
From: dominic_mayers at yahoo dot com Assigned: peehaa (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If you forgot your password, you can retrieve your password here.
Password:
Status:
Package:
Bug Type:
Summary:
From: dominic_mayers at yahoo dot com
New email:
PHP Version: OS:

 

 [2016-09-19 23:53 UTC] dominic_mayers at yahoo dot com 
Description:
------------
---
From manual page: http://www.php.net/language.namespaces.definitionmultiple
---
Though I cannot see anything wrong with the documentation per se, it seems not sufficient, because the User contributed notices that have the most up votes are misleading. They confuse the (unrecommended) non bracketed syntax with the bracketed syntax. They use brackets when they are not needed. For example, one notice with 78 up votes says: 

"use" statements are required to be placed after the "namespace my\space" but before the "{". e.g.

<?php
namespace foo\bar;
use my\space\MyClass;
{

// place code here

} // end of namespace foo\bar

To make things worst, one notice was trying to correct this confusion, saying that, in the correct bracketed syntax, the use statements must be within the brackets. This notice received down votes. So, adding a notice to correct the confusion does not seem to work.   Perhaps, there should be an emphasis that this false bracketed syntax is the same as the non bracketed syntax, but with useless brackets. Perhaps, to make the point clear, it should be mentioned that it's not possible to mix namespaces with the unnamed space when we use semi columns after the namespace statements, even if we add these useless brackets.

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2016-09-20 00:20 UTC] dominic_mayers at yahoo dot com
-Type: Feature/Change Request +Type: Documentation Problem
 [2016-09-20 00:20 UTC] dominic_mayers at yahoo dot com 
This is a documentation problem. I don't know what I was thinking when I classed it in change/feature request.
 [2016-09-20 08:27 UTC] peehaa@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: peehaa
 [2016-09-20 08:27 UTC] peehaa@php.net 
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.

I have removed the user note because it was confusing at best.

Al information is already in http://php.net/manual/en/language.namespaces.importing.php too.
 [2016-09-20 09:30 UTC] dominic_mayers at yahoo dot com 
The documentation in the page itself http://php.net/language.namespaces.definitionmultiple is perhaps the only page that contains relevant, valid and useful information on the issue - it is a good informative page. It says clearly that there are two syntaxes. It's clear from it that there is no semi columns just before the brackets in the bracketed syntax and no need for brackets in the other syntax. The problem was mainly the user notice that received so many up votes and, I agree, was confusing at best. I certainly have been confused by it: for a while, I thought that using a semi column between the namespace statement and the opening bracket was an undocumented version of the bracketed syntax. Because this user notice received so many up votes, I felt perhaps the documentation was not sufficient.
 [2016-09-20 10:02 UTC] dominic_mayers at yahoo dot com 
Can you remove my user notice as well. It became useless and was down voted, perhaps by myself.
 [2016-09-20 11:59 UTC] dominic_mayers at yahoo dot com 
The instructions are clear: do not refer to other user notices and the reason given is exactly what happened : the notice was removed. I am guilty. Since I did not refer to it explicitly, I thought that it will be fine, but it's not. Also, I did not foresee at all that a notice with 78 up votes could be removed.
 [2016-09-20 14:12 UTC] peehaa@php.net 
Your note is also removed now. All should be fixed. Thanks.
 
PHP Copyright © 2001-2026 The PHP Group
All rights reserved. 		Last updated: Thu Oct 08 20:00:02 2026 UTC