Re: [PHP-DOC] Strict standards errors
I can't test it actually, but il seems fine for me. Best, Yannick 2013/9/18 Chris Wright > On Tue, Sep 17, 2013 at 5:08 PM, Yannick Torrès > wrote: > > > I just push a patch for this : > > Great, thanks :-) > > On a related note, can you review > https://github.com/php/web-doc-editor/pull/2 ? > > This has come about because I just reverted an invalid edit on > en/make_chm_index.html and it is now showing up as a documentNotUTF8 error, > because > the current check only looks for . As it happens > the > patch > wouldn't pass this particular file because its tag is wrong as well, > but I'd > like it to pass once I fix this :-P > > Cheers, Chris > > >
RE: [PHP-DOC] Strict standards errors
On Tue, Sep 17, 2013 at 5:08 PM, Yannick Torrès wrote: > I just push a patch for this : Great, thanks :-) On a related note, can you review https://github.com/php/web-doc-editor/pull/2 ? This has come about because I just reverted an invalid edit on en/make_chm_index.html and it is now showing up as a documentNotUTF8 error, because the current check only looks for . As it happens the patch wouldn't pass this particular file because its tag is wrong as well, but I'd like it to pass once I fix this :-P Cheers, Chris
Re: [PHP-DOC] Strict standards errors
I just push a patch for this : http://git.php.net/?p=web/doc-editor.git;a=commitdiff;h=46ed4c5754dc2ed8a541c3168d9b97c7db08c871 It will solve '...' argument warning, but not the "en/language/oop5/decon.xml" warning ;) 2013/9/17 Chris Wright > On Tue, Sep 17, 2013 at 12:34 PM, Yannick Torrès > wrote: > > Could you please give me a filename as example for this ? > > en/reference/array/functions/array-intersect-ukey.xml > en/reference/array/functions/array-multisort.xml > > Interestingly, the following file also has one but doesn't complain about > it (although > it does complain about $args, this is also unresolvable is more like > expected > behaviour): > > en/language/oop5/decon.xml > > The only visible difference here is that the ellipsis arg in __construct() > is untyped. > > Thanks, Chris >
RE: [PHP-DOC] Strict standards errors
On Tue, Sep 17, 2013 at 12:34 PM, Yannick Torrès wrote: > Could you please give me a filename as example for this ? en/reference/array/functions/array-intersect-ukey.xml en/reference/array/functions/array-multisort.xml Interestingly, the following file also has one but doesn't complain about it (although it does complain about $args, this is also unresolvable is more like expected behaviour): en/language/oop5/decon.xml The only visible difference here is that the ellipsis arg in __construct() is untyped. Thanks, Chris
Re: [PHP-DOC] Strict standards errors
About decon.xml, the tag is necessary for the check. See the regex from the last modified file from my last commit Best, Yannick 2013/9/17 Yannick Torrès > I just push a patch for this : > > > http://git.php.net/?p=web/doc-editor.git;a=commitdiff;h=46ed4c5754dc2ed8a541c3168d9b97c7db08c871 > > It will solve '...' argument warning, but not the "en/language/oop5/decon.xml" > warning ;) > > > 2013/9/17 Chris Wright > >> On Tue, Sep 17, 2013 at 12:34 PM, Yannick Torrès < >> yannick.tor...@gmail.com> wrote: >> > Could you please give me a filename as example for this ? >> >> en/reference/array/functions/array-intersect-ukey.xml >> en/reference/array/functions/array-multisort.xml >> >> Interestingly, the following file also has one but doesn't complain about >> it (although >> it does complain about $args, this is also unresolvable is more like >> expected >> behaviour): >> >> en/language/oop5/decon.xml >> >> The only visible difference here is that the ellipsis arg in >> __construct() is untyped. >> >> Thanks, Chris >> > >
Re: [PHP-DOC] Strict standards errors
Could you please give me a filename as example for this ? 2013/9/16 Hannes Magnusson > On Sun, Sep 15, 2013 at 3:27 PM, Chris Wright wrote: > > I've pushed a couple of commits to clear the backlog here and > > something that is definitely a problem with the checker is that it > > considers varargs to have a missing initializer. Having the strict > > standards checker ignore any thing structured like this: > > > > > > ... > > > > > > ...might cut down the size of the queue somewhat (i.e. ignoring > > arguments named as an ellipsis). > > > > I know the majority of array functions that have missingInitializer > > errors are suffering from this issue. > > > > Thoughts? > > > > I guess it makes sense to ignore a parameter called "..." from this check. > > -Hannes >
Re: [PHP-DOC] Strict standards errors
On Sun, Sep 15, 2013 at 3:27 PM, Chris Wright wrote: > I've pushed a couple of commits to clear the backlog here and > something that is definitely a problem with the checker is that it > considers varargs to have a missing initializer. Having the strict > standards checker ignore any thing structured like this: > > > ... > > > ...might cut down the size of the queue somewhat (i.e. ignoring > arguments named as an ellipsis). > > I know the majority of array functions that have missingInitializer > errors are suffering from this issue. > > Thoughts? I guess it makes sense to ignore a parameter called "..." from this check. -Hannes
Re: [PHP-DOC] Strict standards errors
I've pushed a couple of commits to clear the backlog here and
something that is definitely a problem with the checker is that it
considers varargs to have a missing initializer. Having the strict
standards checker ignore any thing structured like this:
...
...might cut down the size of the queue somewhat (i.e. ignoring
arguments named as an ellipsis).
I know the majority of array functions that have missingInitializer
errors are suffering from this issue.
Thoughts?
Thanks, Chris
On 10 September 2013 09:10, Chris Wright wrote:
> OK great. I'll make a start on correcting the obvious ones and leave
> any I'm not sure about alone, hopefully we can get the outstanding
> list down to just these cases fairly quickly, which will quite
> effectively separate the wheat from the chaff, and we can take another
> look at the situation at that stage :-)
>
> On 10 September 2013 01:41, Hannes Magnusson
> wrote:
>> That's a slightly different issue though.
>>
>> In general functions with optional arguments have default value, or can be
>> faked with for example empty array or null. In those cases we should use
>> that for the initializer argument.
>>
>> For others, I think we need to evaluate them on case by case bases what our
>> options are.
>>
>> -Hannes
>>
>> On Sep 9, 2013 5:08 PM, "Chris Wright" wrote:
>>>
>>> On 10 September 2013 00:28, Hannes Magnusson
>>> wrote:
>>> > IMO an optional argument should have a way to "skip it, using default
>>> > value".
>>> > its annoying when in userland you have to do
>>> > if ($option) {
>>> > foo($arg1, $arg2, $option);
>>> > } else {
>>> > foo($arg1, $arg2);
>>> > }
>>> >
>>> > And I consider it a bug when I cannot pass empty string/array/null to
>>> > the optional parameter.
>>>
>>> Agreed. This is closely related to recent discussions on internals,
>>> and without wishing to bring that particular open can of worms over
>>> here I think it would be good to account for the possibility in docs.
>>> My first thought would be to add a phpdoc:skippable="true" (or
>>> something) attribute to parameters, which would possibly have some
>>> form of semantic meaning in the rendered version if any of the
>>> parameter proposals were to make through but, on this topic, would
>>> negate a missingInitializer error. Obviously this would only be valid
>>> for choice="opt" parameters.
>>>
>>> This may be a really bad idea, so please feel free to send any
>>> comments/alternative ideas/abuse in my general direction.
>>>
>>> Cheers, Chris
Re: [PHP-DOC] Strict standards errors
OK great. I'll make a start on correcting the obvious ones and leave
any I'm not sure about alone, hopefully we can get the outstanding
list down to just these cases fairly quickly, which will quite
effectively separate the wheat from the chaff, and we can take another
look at the situation at that stage :-)
On 10 September 2013 01:41, Hannes Magnusson wrote:
> That's a slightly different issue though.
>
> In general functions with optional arguments have default value, or can be
> faked with for example empty array or null. In those cases we should use
> that for the initializer argument.
>
> For others, I think we need to evaluate them on case by case bases what our
> options are.
>
> -Hannes
>
> On Sep 9, 2013 5:08 PM, "Chris Wright" wrote:
>>
>> On 10 September 2013 00:28, Hannes Magnusson
>> wrote:
>> > IMO an optional argument should have a way to "skip it, using default
>> > value".
>> > its annoying when in userland you have to do
>> > if ($option) {
>> > foo($arg1, $arg2, $option);
>> > } else {
>> > foo($arg1, $arg2);
>> > }
>> >
>> > And I consider it a bug when I cannot pass empty string/array/null to
>> > the optional parameter.
>>
>> Agreed. This is closely related to recent discussions on internals,
>> and without wishing to bring that particular open can of worms over
>> here I think it would be good to account for the possibility in docs.
>> My first thought would be to add a phpdoc:skippable="true" (or
>> something) attribute to parameters, which would possibly have some
>> form of semantic meaning in the rendered version if any of the
>> parameter proposals were to make through but, on this topic, would
>> negate a missingInitializer error. Obviously this would only be valid
>> for choice="opt" parameters.
>>
>> This may be a really bad idea, so please feel free to send any
>> comments/alternative ideas/abuse in my general direction.
>>
>> Cheers, Chris
Re: [PHP-DOC] Strict standards errors
That's a slightly different issue though.
In general functions with optional arguments have default value, or can be
faked with for example empty array or null. In those cases we should use
that for the initializer argument.
For others, I think we need to evaluate them on case by case bases what our
options are.
-Hannes
On Sep 9, 2013 5:08 PM, "Chris Wright" wrote:
> On 10 September 2013 00:28, Hannes Magnusson
> wrote:
> > IMO an optional argument should have a way to "skip it, using default
> value".
> > its annoying when in userland you have to do
> > if ($option) {
> > foo($arg1, $arg2, $option);
> > } else {
> > foo($arg1, $arg2);
> > }
> >
> > And I consider it a bug when I cannot pass empty string/array/null to
> > the optional parameter.
>
> Agreed. This is closely related to recent discussions on internals,
> and without wishing to bring that particular open can of worms over
> here I think it would be good to account for the possibility in docs.
> My first thought would be to add a phpdoc:skippable="true" (or
> something) attribute to parameters, which would possibly have some
> form of semantic meaning in the rendered version if any of the
> parameter proposals were to make through but, on this topic, would
> negate a missingInitializer error. Obviously this would only be valid
> for choice="opt" parameters.
>
> This may be a really bad idea, so please feel free to send any
> comments/alternative ideas/abuse in my general direction.
>
> Cheers, Chris
>
Re: [PHP-DOC] Strict standards errors
On 10 September 2013 00:28, Hannes Magnusson wrote:
> IMO an optional argument should have a way to "skip it, using default value".
> its annoying when in userland you have to do
> if ($option) {
> foo($arg1, $arg2, $option);
> } else {
> foo($arg1, $arg2);
> }
>
> And I consider it a bug when I cannot pass empty string/array/null to
> the optional parameter.
Agreed. This is closely related to recent discussions on internals,
and without wishing to bring that particular open can of worms over
here I think it would be good to account for the possibility in docs.
My first thought would be to add a phpdoc:skippable="true" (or
something) attribute to parameters, which would possibly have some
form of semantic meaning in the rendered version if any of the
parameter proposals were to make through but, on this topic, would
negate a missingInitializer error. Obviously this would only be valid
for choice="opt" parameters.
This may be a really bad idea, so please feel free to send any
comments/alternative ideas/abuse in my general direction.
Cheers, Chris
Re: [PHP-DOC] Strict standards errors
On Mon, Sep 9, 2013 at 3:37 PM, Chris Wright wrote:
> - What sort of timescale are we looking at for this (I'm not expecting
> dates but maybe weeks vs. months vs. years?)
We do things whenever we have time.
This change is even more tricky (although easier in some respect) then
the -> docbook5 bump, or xslt or phd..
I'd guess months, although my initial timeframe was a symbolic October
1st (PhD turns 6years old).
> - The only outstanding strict standards errors remaining are
> missingInitializer errors. The vast majority of these are arguably not
> really errors - many functions that take an optional arg don't really
> have a default value for those args, especially those functions that
> take by-ref output args (for example exec()). Can we do something
> about this (and is it worth it given the answer to Q1)?
Since we will be moving to more of a freeform format it is important
that all pedantic consistency issues are in as good shape as possible.
Initializers are also important, arguments that are by-reference
should indicate the "return type".
> For this second question, really there are three options:
>
> - Change any args that don't really have a default value to an
> initializer of null, which is the closest that PHP has to a convention
> in this respect
IMO an optional argument should have a way to "skip it, using default value".
its annoying when in userland you have to do
if ($option) {
foo($arg1, $arg2, $option);
} else {
foo($arg1, $arg2);
}
And I consider it a bug when I cannot pass empty string/array/null to
the optional parameter.
> My main reason for clearing out these backlogs is that backlogs cause
> the tools to become less useful, old things hanging around just
> becomes noise. Ideally I'd like to see everything emptied (and I'm
> quite prepared to put the work in to accomplish this) but I don't want
> to do it if we will be scrapping docbook in a fortnight, and I want to
> make sure that the community is agreed with the direction any work
> I/we do put in.
Keep it going! :)
I believe most of the 'strict' rules are very beneficial in the long
run, irregardless of of/when we kill docbook.
-Hannes
Re: [PHP-DOC] Strict standards errors
Tangent: On Mon, Sep 9, 2013 at 4:37 PM, Chris Wright wrote: > > I know the new MD-esque format is pretty much definitely going to > happen... Docs migration is a serious subject that needs more discussion if it's going to happen.
