Re: svn: /phpdoc/en/trunk/reference/filesystem/functions/ file-get-contents.xml

From: Date: Wed, 28 Apr 2010 11:03:35 +0000
Subject: Re: svn: /phpdoc/en/trunk/reference/filesystem/functions/ file-get-contents.xml
References: 1 2 3 4 5 6 7 8 9  Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-6503@lists.php.net to get a copy of this message
On 28 April 2010 10:58, Richard Quadling <rquadling@googlemail.com> wrote: > On 27 April 2010 19:11, Philip Olson <philip@roshambo.org> wrote: >> >> On Apr 27, 2010, at 8:59 AM, Richard Quadling wrote: >>> On 27 April 2010 16:52, Richard Quadling <rquadling@googlemail.com> wrote: >>>> On 27 April 2010 16:05, Hannes Magnusson <hannes.magnusson@gmail.com> wrote: >>>>>>>> When was that argument renamed again? >>>>>>>> Its called flags in 5.3 atleast.. >>>>>>>> >>>>>>> >>>>>>> >>>>>>> http://svn.php.net/viewvc/php/php-src/trunk/ext/standard/file.c?view=annotate#l520 >>>>>>> >>>>>>> http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/file.c?view=annotate#l521 >>>>> >>>>> What the proto or zpp() uses is irrelevant. >>>>> >>>>> bjori@jessica:~$ php --rf file_get_contents >>>>> Function [ <internal:standard> function file_get_contents ] { >>>>> >>>>>  - Parameters [5] { >>>>>    Parameter #0 [ <required> $filename ] >>>>>    Parameter #1 [ <optional> $flags ] >>>>>    Parameter #2 [ <optional> $context ] >>>>>    Parameter #3 [ <optional> $offset ] >>>>>    Parameter #4 [ <optional> $maxlen ] >>>>>  } >>>>> } >>>> >>>>>>> Both show the param as bool use_include_path and retrieve it as a >>>>>>> 'b' >>>>>> >>>>>> This is why I changed the type in this commit. With these changes, the >>>>>> description to use FILE_USE_INCLUDE_PATH conflicts somewhat if we are >>>>>> asking people to use a boolean.  Any suggestions for the description; >>>>>> the constant will still work since its value is 1 but should we ignore >>>>>> that fact? What about people who might already be using >>>>>> FILE_USE_INCLUDE_PATH? >>>>> >>>>> I think we should pretend that the parameter is int, called flags, and >>>>> mention that FILE_USE_INCLUDE_PATH is defined as 1 so passing boolean >>>>> is fine. >>>> >>>> >>>> >>>> The zpp code requires a boolean. >> >> I think file_get_contents() is a special case that should keep in mind FC. While reverting >> "PHP 6" stuff, it was the one piece of documentation that required changing an entire >> subset (parameters) of documentation, so keeping this in mind by hinting what the future brings >> feels right. >> >> Hannes suggests a FC friendly fix but I wonder, are we 100% certain that BC is kept? >> Meaning, boolean values will always work as they do today? In which case, 0,false === no flags, >> 1,true,FILE_USE_INCLUDE_PATH === that flag, and other ints === other [future] flag combinations. How >> about keeping it as 'flags' and documenting it like this? >> >> Regards, >> Philip >> >> >> > > If use_include_path => flags, then as long as flags is documented to > only have 1 flag (FILE_USE_INCLUDE_PATH), then all would be fine. I'm inclined to vote for this approach; we do have other functions which have only a single flag. It allows the current boolean/flag value to be acceptable but with a nod towards more flags being available in the future. > It would be nice to have the prototype correct in the code so dweebs like > me can read the c code and at least be half way right about what is > going on. Absolutely, my first port of call is usually the commented prototype and then the source of the function that the prototype is commenting. As this thread shows, having arguments labelled differently in multiple places can and will confuse matters. Would changing the source to use long/flags (from bool/use_include_path) not be a good idea for any technical reasons, or would it be OK to do that? > > Richard. > > -- > ----- > Richard Quadling > "Standing on the shoulders of some very clever giants!" > EE : http://www.experts-exchange.com/M_248814.html > EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp > Zend Certified Engineer : > http://zend.com/zce.php?c=ZEND002498&r=213474731 > ZOPA : http://uk.zopa.com/member/RQuadling > > -- > PHP Documentation Commits Mailing List (http://www.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > >

« previous php.doc.cvs (#6503) next »