On 24-02-2012 23:12, Ronald Chmara wrote:
On Fri, Feb 24, 2012 at 1:54 PM, Maciek Sokolewicz
<maciek.sokolew...@gmail.com> wrote:
The reason I'm using such "strict" guidelines is simply
to make the manual notes readable. If you look at a page such as
http://www.php.net/manual/en/function.strtotime.php, there are> 100 notes
present. Trying to find something useful to you is simply impossible on such
a page.
I disagree. The problem is not that there are too many notes. (That's
a bit like complaining the internet has too many pages). The problem
on that page is that strtotime isn't documented in such a way as to
make the many notes unnecessary.
I disagree, see below why.
Trying to clean that page to only leave samples that solve very
common problems or clarify the behaviour of the function is IMO a good
thing. That does often mean removing various code samples of the type "this
might be useful to some people".
I am wondering what others think, should we try to thin down the stream of
notes and simply delete notes that have little to say about the actual
function or are of relatively little use to the common PHP coder? Or should
we leave as many notes as possible with examples so people can find
*anything* in there? Possibly leading to unwieldy long lists of notes?
What do YOU think? Feel free to comment / criticise / be constructive ;)
Notes, to me, are an indication of what is lacking in the manual. If
you want to delete a note, make sure the content/idea/concept has
already been put into the documentation somehow. Update the
documentation, *then* delete the note. Simply deleting a note adds no
value to the project. A page with many notes is a page in need of a
re-write, not a note purge.
-Ronabop
I agree that many notes may mean that the documentation is not
explenatory enough, that is IMO not always the case. If you look at the
strtotime page, you would be adding the following examples to the manual:
- how to make "strotime work with dates prior to 1970"
- how "next month" is interpreted in edge cases
- the fact that mm/dd/yyyy is a US date format, while dd/mm/yyyy is a
european format
- weeks start on sunday
- how to parse dates stored in MySQL
- how to calculate the time passed since a certain date (ie. timediff)
- how to loop through date ranges
- possible misunderstandings in the interpretation of dates by strotime
- the fact that you have to escape modifiers
- how to "add time" using strtotime
- how to handle specific time formats using strtotime
- how to calculate bank holidays
- how to convert dates from some specific format to another
- the fact that strtotime produces different output on 32bit machines
than it does on 64bit
- workarounds to make a different day the first day of the week
etc.
Some of these, I agree, should indeed be added to the manual. However,
many are simply showing possible ways to work with the function. Not
something that many people would *need*. The documentation is IMO not a
place to hold every possible use of the function. It's a place where you
go to find out how it works, and in the notes any interesting sidenotes
about why it may not work as expected.
Examples are added to clarify how to work with the function, but
providing every possible way of using it (potentially millions) is
simply not useful.
My other point is that such spam drowns out the useful notes, such as
the one explaining differences in function behaviour between 32bit and
64bit systems. Instead you find a zillion notes explaining how you can
emulate behaviour of other functions using this one.
